CloudAPIGuide BusinessFlows

Guidewire PolicyCenter™
for Guidewire Cloud
Cloud API Business Flows and

Configuration Guide
Release 2022.05
© 2022 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: 2022.05
Document Name: Cloud API Business Flows and Configuration Guide
Document Revision: 19-August-2022
Guidewire PolicyCenter for Guidewire Cloud 2022.05 Cloud API Business Flows and Configuration Guide
Contents
Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Part 1
Consuming Cloud API
1 REST API fundamentals in Cloud API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
The InsuranceSuite Cloud API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Root resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Child resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
Requests and responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Testing requests and responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Tutorial: Set up your Postman environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
2 Overview of the system APIs in Cloud API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

The base configuration system APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Cloud API versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Viewing API definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Swagger UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
View an API definition using Swagger UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Organization of API information in Swagger UI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
The API definition endpoints and Postman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
View an API definition using Postman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Organization of information in the output of API definition endpoints . . . . . . . . . . . . . . . . . . . . .32
Beta APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Published APIs and endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Beta APIs and endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Beta APIs for this release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Routing related API calls in clustered environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
3 GETs and response payload structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Overview of GETs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Standardizing payload structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Viewing response 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
The attributes section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
The checksum field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
The links subsection (for an element) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
3
The collection-level links section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

Payload structure for a response with included resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
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) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Including either a collection or a specific resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Determining which resources can be included . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
4 Refining response payloads using query parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Overview of query parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Viewing query parameter documentation in Swagger UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Query parameter error messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Specifying the resources and fields to return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Filtering GETs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Tutorial: Send a GET with the filter parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Specifying which fields to GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Tutorial: Send a GET with the fields parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Getting resources "as of" a certain date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Sorting the result set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Tutorial: Send a GET with the sort query parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Controlling pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Limiting the number of resources per payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Selecting a single resource in a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Paging through resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Retrieving the total number of resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Tutorial: Send a GET with the pageSize and totalCount parameters . . . . . . . . . . . . . . . . . . . . . . .59
Using query parameters on included resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Specifying query parameters that apply to an included resource . . . . . . . . . . . . . . . . . . . . . . . . . .60
Summary of query parameters for included resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Tutorial: Send a GET with query parameters for included resources . . . . . . . . . . . . . . . . . . . . . . .61
5 POSTs and request payload structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

Overview of POSTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Standardizing payload structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Viewing request schemas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
View a request schema in Swagger UI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Designing a request payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Determining the required, optional, and write-only fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Request payload structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Specifying scalar values in a request payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Specifying objects in a request payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Setting values and objects to null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Sending POSTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Send a POST using Postman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Tutorial: Create a new note that specifies required fields only . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Tutorial: Create a new note that specifies optional fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Responses to a POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Postman behavior with redirects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Business action POSTs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Improving POST performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
6 PATCHes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Overview of PATCHes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
The PATCH payload structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Designing a request payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
4
PATCHes and arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Sending PATCHes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Send a PATCH using Postman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Tutorial: PATCH an activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Responses to a PATCH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
PATCHes and lost updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Postman behavior with redirects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
7 DELETEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Overview of DELETEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Tutorial: DELETE a note. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
DELETEs and lost updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
8 Reducing the number of calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Features that execute multiple requests at once . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Comparing features that execute multiple requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Determining which feature to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
9 Composite requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

Constructing composite requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
The requests section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Using variables to share information across subrequests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Responses to the subrequests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
The selections section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Composite request limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Administering composite requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Configuring the maximum number of subrequests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Complete composite request syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
10 Request inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

Syntax for simple parent/child relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Syntax for named relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Additional request inclusion behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
11 Batch requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Batch request syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Optional subrequest attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Batch request examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Simple batch requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Batch requests with query parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Batch requests with request payloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Batch requests with distinct operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Administering batch requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Specifying subrequest headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Specifying onFail behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Configuring the maximum number of subrequests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
12 Lost updates and checksums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Lost updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Checksums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Checksums for PATCHes and business action POSTs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Tutorial: PATCH an activity using checksums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Tutorial: Assign an activity using checksums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Checksums for DELETEs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Send a checksum in a request header using Postman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
5
Tutorial: DELETE a note using checksums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
13 Cloud API headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

HTTP headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Overview of Cloud API headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Send a request with a Cloud API header using Postman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Preventing duplicate database transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Warming up an endpoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Handling a call with unknown elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Validating response payloads against additional constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
14 Globalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Specifying language and locale in API requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Addresses and locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Address locale configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Part 2
Business flows: Accounts
15 Creating accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Creating an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
The account holder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
The primary location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
The producer code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Creating an account example payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Name clearance and account status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Child objects for an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Creating accounts as an anonymous user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
16 Managing accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Querying for accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Searching for accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Modifying accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Account contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Querying for account contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Creating account contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Modifying account contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Account locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Querying for account locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Creating account locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Modifying account locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Account jobs and policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
17 Managing bound policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Querying for policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Searching for policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Moving policies between accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Policy producers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Policy jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Policy contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Policy locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Policy questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Additional actions for bound policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
6
Part 3
Business flows: Job types
18 Policy transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Initiating the policy transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Modifying the job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Quoting the job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Completing the policy transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
LOB-specific endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
19 Submissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Initiating a submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Modifying the submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Quoting the submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Completing the submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Binding and issuing a submission at the same time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Binding a submission without issuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Issuing a previously bound policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Withdrawing and rejecting submissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Copying submissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Additional features for submissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
20 Renewal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Renew the policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
21 Policy change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Change the policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Preemptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Identifying that a job has been preempted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Viewing preemption information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Handling preemptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Applying changes to a renewal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
22 Cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Cancel the policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
23 Reinstatement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Reinstate the policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
24 Rewrite and Rewrite New Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Rewrite transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Rewrite new account transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Part 4
Business flows: Job policies
Overview of modifying jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
25 Lines of business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Overview of lines of business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Additional LOB-specific endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Contrasting job, policy, product, and line of business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
26 Coverables and coverages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Overview of coverables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Adding coverables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
7
Overview of coverages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Adding coverages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Coverage terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Coverage validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
27 Modifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Overview of modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Specifying modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Modifier validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
28 Questions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Overview of questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Answering questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Specifying answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Question validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
29 Exposures, exclusions, and conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Overview of exposures, exclusions, and conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Adding exposures, exclusions, and conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
30 Synchronization and deferred validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Out-of-sync policy data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
The /sync endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
The /sync-coverages endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
The /sync-fields endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
The /sync-modifiers endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
The /sync-questions endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
When to call a /sync endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Deferring validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
The deferValidation query parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Authorization to defer validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Limitations to deferred validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
The createDefaultCoverages query parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
31 Policy contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Overview of policy contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Working with all policy contacts on a job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Querying for all policy contacts on a job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Adding an account contact to a job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
PATCHing and DELETEing policy contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Primary named insured contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Additional named insured contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Querying for additional named insureds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Adding additional named insureds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
PATCHing and DELETEing additional named insureds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
32 Policy locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Overview of policy locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Querying for a policy's locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Creating policy locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
PATCHing policy locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
DELETEing policy locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Job user role assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Overview of job role assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Retrieving job user roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Assigning job user roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
PATCHing job roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8
33 Working with product definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
34 PATCHing jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Read-only fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Fields you can modify using PATCH /{jobId} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Fields you can modify using specific endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Part 5
Business flows: Job support
Comparing jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Comparing a job to its base policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Structure of the JobReviewDiffs resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Example of a /review-diffs response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Comparing two jobs on the same policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Structure of the CompareJobAttributes resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
35 Contingencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Querying for contingencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Creating contingencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Closing contingencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
36 Policy and job search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
37 Out-of-sequence conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Identifying out-of-sequence conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Resolving out-of-sequence conflicts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Example: Identifying and resolving out-of-sequence conflicts. . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
38 Quoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Multi-version quoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Job version properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Creating a new job version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Selecting a job version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Working with job versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Rating overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Rating overrides in Cloud API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
39 Underwriting issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Underwriting issues in PolicyCenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Querying for underwriting issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Creating underwriting issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Minimum creation criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Examples of creating an underwriting issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Managing underwriting issue approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Approval underwriting issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Rejecting underwriting issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Reopening underwriting issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Job locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Locking jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Releasing locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Requesting approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Requesting approval through Cloud API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Referral reasons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Querying for referral reasons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Creating referral reasons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Closing and reopening referral reasons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
9
Part 6
Business flows: Framework APIs
40 Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Querying for activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Creating activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Assigning activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Assignment options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Assignment examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Retrieving recommended assignees. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Closing activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Additional activity functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
41 Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Overview of documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Querying for document information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Querying for document metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Querying for document content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
POSTing documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
POSTing documents using Postman . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
PATCHing documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
DELETEing documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
42 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Querying for notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Creating account, job, and policy notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Additional notes functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
43 Users and groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Querying for users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Creating users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Updating users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Querying for groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Assigning users to groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
User roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Querying for user roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Creating user roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Updating user roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Authority profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Retrieving information about underwriting authority profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Assigning authority profiles to users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Creating authority profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Modifying authority profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Authority profile grants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Querying for grants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Creating grants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
c_modifying-grants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
44 Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Querying for organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Creating organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Updating organizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
10
45 Producer codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Querying for producer codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Creating producer codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Updating producer codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Managing a user's producer codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Querying for a user's producer codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Associating producer codes with users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Exposing producer codes to external users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Part 7
Configuring Cloud API
46 Configuring schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Overview of resource definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Resource definition file architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Reasons to modify resource definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Syntax for resource definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Schema file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Mapping file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Updater file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Extension files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Data mapping for new properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
Data mapping for scalars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Data mapping for new compound values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Tutorial: Data mapping for new properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Additional behaviors for properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Read-only properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Properties required by the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Properties writeable at creation only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Sortable properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Additional metadata for properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Summary of property attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Collection-level behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Sorting a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Filtering a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Swagger files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Apiconfig files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Tutorial: Extending a data model entity and its API resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
47 Obfuscating Personally Identifiable Information (PII). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Nullifying PII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Masking PII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
48 Localizing schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Architecture of localized text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Associating display keys with API elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Localization key prefixes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Display key patterns for schema.json-files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Display key patterns for swagger.yaml files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Providing locale specific content for a given locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Adding localized text for existing API elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Adding localized text for new API elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Adding a new locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
11
49 APIs for lines of business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

Generating and installing LOB-specific APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Generating LOB-specific APIs through APD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Generating templates from a finalized product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Installing LOB-specific APIs without installing other artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . 368
API codegen configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Disabling product artifacts during testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Determining which product artifacts to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Disable a product's visualized artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Enable a product's visualized artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Disable a product's installed artifacts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Managing LOB-specific APIs for testing and integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Importing a product template through the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Querying for product templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Toggling the active state of a visualized product. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Generating code from a visualized product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Deleting a product template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Generating endpoints for specific products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
The base configuration Personal Auto product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Part 8
Generating endpoints for custom entities
50 The REST endpoint generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
REST endpoint generator overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Architecture of custom CRUD endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
REST endpoint generator restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Special use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
51 Running the REST endpoint generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Issues to consider before running the generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
The API for the new endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
The parent of the custom resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Populating collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Additional considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Running the REST endpoint generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Running the REST endpoint generator from Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Create a run configuration for the REST endpoint generator . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Use the run configuration to run the REST endpoint generator . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Running the REST endpoint generator from the command prompt . . . . . . . . . . . . . . . . . . . . . . . 393
The REST endpoint generator prompts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Completion of the script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Completing the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
52 Configuring the resource definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

The resource definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Configuring the schema file for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Overview of schema file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Modifications made to the schema file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Syntax for property types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Additional properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Configuring the mapping file for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Overview of mapping file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Modifications made to the mapping file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Mapping syntax for property paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
12
Configuring the updater file for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

Overview of updater file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Modifications made to the updater file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Updater syntax for property paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Configuring the swagger file for generated endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Overview of swagger file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Modifications made to the swagger file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
53 Configuring glue and impl classes for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

The glue and impl classes for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Configuring the apiconfig file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Configuring the element resource file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Configuring the collection resource file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
54 Configuring authorization for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Configuring endpoint access for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Code generated in role.yaml files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Configuring code in role.yaml files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Configuring resource access for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Code generated in access.yaml files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Generated resource access code for internal users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Generated resource access code for external users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Generated resource access code for services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Generated resource access code for special use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Configuring generated resource access code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Configuring generated resource access code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
55 Generating endpoints for ClaimCenter Policy graph entities . . . . . . . . . . . . . . . . . . . . . . . . . . 429

Creating Policy descendant endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Policy as a parent to the custom resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
REST endpoint generator variances for Policy endpoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Configuring variances for glue and impl classes for Policy endpoints . . . . . . . . . . . . . . . . . . . . . 429
Configuring variances for the apiconfig file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Configuring variance for Policy resource files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Creating custom risk units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Risk unit criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
REST endpoint generator variances for custom risk units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Configuring variances for glue and impl classes for risk units . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Configuring variances for risk unit resource files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Inline damageables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
56 Additional considerations for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Integration graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
The graph schema file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
The graph mapper file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
The apiconfig mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
13
14
Support
For assistance, visit the Guidewire Community.

Guidewire customers
https://community.guidewire.com
Guidewire partners
https://partner.guidewire.com
Support 15
16 Support
Part 1
Consuming Cloud API
The 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 provide content for the REST API framework
that is present in all InsuranceSuite applications. The APIs are built using the Swagger 2.0 Specification. These are
also referred to as the system APIs.
The following topics discuss how caller applications can consume the system APIs in Cloud API. This includes how
to:
• Construct GET requests to query for data
• Construct POST requests to create new data
• Construct PATCH requests to modify existing data
• Construct DELETE requests to remove data
• Use query parameters to refine response payloads
• Reduce the number of calls needed to accomplish a business flow
• Prevent lost updates using checksums
chapter 1
REST API fundamentals in Cloud API
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.
For information on functionality specific to the APIs in the Cloud API (such as the APIs that exist in the base
configuration, the beta APIs, or the openapi.json endpoints), see “Overview of the system APIs in Cloud API” on
page 27.
The InsuranceSuite Cloud API

The 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 provide content for the REST API framework
that is present in all InsuranceSuite applications. The APIs are built using the Swagger 2.0 Specification. These are
also referred to as the system APIs.
The system 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 a system API.
Making system API calls
The following diagram provides a high-level overview of the interaction between the caller application and the
system APIs.
REST API fundamentals in Cloud API 19

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 the system API using an HTTP command.
• The command calls a specific API endpoint.
• The command may include query parameters that further identify the data that is desired.
• The request object is sent with the command.
3. The system 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 the system APIs.
4. The system 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.
System APIs and InsuranceSuite logic

In the software industry, some RESTful APIs are configured to interact directly with the database. The system APIs
are not configured to behave this way. The system APIs interact with operational data only through the layer of the
application's business logic. Therefore, the system APIs always leverage 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 the system APIs, 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 a system 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",
20 chapter 1: REST API fundamentals in Cloud API

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

• A scalar value, such as the subject field.
• A set of values, such as the assignedUser field. This is referred to as an inline object.
• An array of objects. (There is no example of this in Activity. If there were, the field name would be followed by
square braces ([ and ]) delimiting the array. Each array member would be listed in curly braces ({ and }).
Every resource can be uniquely defined by its resource ID. This value maps to the data model entity's PublicID
field. The activity in the previous example is activity xc:20.
A single resource is called an element. For example, /contact/xc:203 is an element. (In some REST API literature,
this is also referred to as a singleton.)
A set of resources is called a collection. For example, /contact/xc:203/addresses (the addresses associated with
contact xc:203) is a collection.
Endpoints
Every API consists of a set of endpoints. An endpoint is a command that a caller application can use to request data
from or trigger action in 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, operations, 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 and response payload structures” on page 35.
Operations
An operation is a type of action a caller application can take on a resource through an endpoint. Operations are also
referred to as verbs or methods. The system APIs support the following subset of HTTP operations:
• GET - Used to request resources.
• POST - Used to create resources. Also used to execute business actions, such as quoting a submission or
submitting a claim.
• PATCH - Used to update resources.
• DELETE - Used to delete resources.
Every endpoint supports one or more of these operations. 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 operations are designed for CRUD operations (Create, Read, Update, Delete). Some business processes
in InsuranceSuite applications are available to the system APIs 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 operation.
Operation mapping to elements and collections
In general:
• You can GET either an element or a collection.
• You POST a collection to create an element.
• You POST to a custom action (to execute a business action).
• You PATCH an element.
• You DELETE an element.
For example:
Operation 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 operations
Technically speaking, when an endpoint supports multiple operations, it is still a single endpoint. However, in casual
discussion, each operation 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 operations (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 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. The system APIs support 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.
Paths
Every endpoint has a path. The path is the portion of the URL used by caller applications to identify the specific
endpoint.
For Cloud API, every path consist of the following pattern:
rest/<APIname>/<APImajorVersion>/<endpointName>
For example, consider the path: rest/common/v1/activities:

• common is the name of the API to which the endpoint belongs.
• v1 is the major version number of the API
• activities is the endpoint name
The major version number provides information about the backwards compatibility of the endpoint. For more
information, see “Cloud API versions” on page 28.
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.
◦ 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
and response payload structures” 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 indi-
cates 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.

Status code Category Meaning

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 system APIs 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 is also able to send requests to a working API and show responses. However, the system APIs are
significantly robust, and performance time for getting responses to requests can be unacceptably long. Guidewire
recommends using Swagger UI only for viewing system API documentation.
Tutorial: Set up your Postman environment

The system 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.
Note: 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.
Troubleshooting: NotFoundException
Unless it is stated otherwise, all of the tutorials use basic authentication and the aapplegate user. If you encounter a
NotFoundException such as the following example, this could be caused by not providing correct authentication
information for this user.
"status": 404,
"errorCode": "gw.api.rest.exceptions.NotFoundException",
"userMessage": "No resource was found at path /common/v1/activities"

chapter 2
Overview of the system APIs in Cloud

API
This topic provides an overview of the system APIs in the Cloud APIs. This includes a discussion of the base
configuration APIs, the tools available for viewing API information, and the beta APIs.
The base configuration system APIs

The base configuration includes the following system APIs:
Name Description Path

Policy API for policies and policy-specific objects /policy/v1
Account API for accounts and account-specific objects /account/v1
Job API for jobs and job-specific objects /job/v1
Product Definition API for PolicyCenter product definition metadata /productdefinition/v1

(This is a Beta API that is available only when enabled.)
Common API for common InsuranceSuite platform objects like /common/v1
activities and notes
API List Dynamically lists the APIs that are available /apis
You can use the API path to view metadata about the API. This is discussed in detail in the following section.
There are also a minimal set of APIs for ContactManager. For more information, refer to the <appURL>/rest/apis
endpoint for ContactManager.
Overview of the system APIs in Cloud API 27

Cloud API versions

Note: The following section defines what a minor release is. Minor releases are not expected to have
"breaking changes". The types of changes that do and do not fall into the definition of "breaking
change" are described in the Schema Backwards Compatibility Contract. To access a copy of this
contract, consult your Guidewire representative.
Every version of Cloud API has a version number. For example, suppose that there were four releases of the system
APIs in January, April, July, and October of a given year. Each release could have the following version numbers:
• January: 1.0.0
• April: 1.1.0
• July: 1.2.0
• October: 2.0.0
Minor and major releases

In future releases, system API functionality is expected to change. To define and control these changes, the Cloud
API makes use of minor versions and major versions.
• A minor version is a version of the Cloud API in which functionality is either identical to the previous release or
additive.
• A major version is a version of the Cloud API in which functionality has changed from the previous release.
A given release of the Cloud API can have multiple versions of the APIs, some of which are minor and some of
which are major.
Major versions are indicated by the "endpoint path number" in API endpoint paths. This is the number that appears
after the "/v". (For example, in /common/v1/activities, the endpoint path number is 1.) When Guidewire makes a
change to an API that is not purely additive, the changed API is considered a major release. Its endpoint number is
incremented by 1.
When a release of the Cloud API includes a new major release, the previous minor release is also included. The
minor release may be identical to the previous release, but it may also have additive changes.
For example, suppose that for the releases from the previous example:
• The Cloud API in the January release is major version 1.
• The Cloud API in the April release is identical or additive.
• The Cloud API in the July release is identical or additive.
• The Cloud API in the October release includes changes to existing functionality.
In this case, the January, April, and July releases would all include a single version of the APIs whose endpoint
included "/v1". The October release would both the "/v1" set of APIs and a new "/v2" set of APIs. This is
summarized in the following table.
Release Version # Compared to the previous release, this Major versions in this release
Month release...
January 1.0.0 ...is identical or additive /common/v1
April 1.0.1 ...is identical or additive /common/v1
July 1.0.2 ...is identical or additive /common/v1
October 2.0.0 ...includes changes to existing /common/v1 (identical or additive to July's release) and
functionality /common/v2 (containing the changed functionality)
28 chapter 2: Overview of the system APIs in Cloud API

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 payloads are structured
• The resources used by each endpoint
• The fields available in each resource
• The properties that apply to each field
These are the common approaches for viewing API definitions in Cloud API:
• Using Swagger UI
• Calling the /openapi.json endpoint (or the /swagger.json) through a request tool
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 expended
and collapsed. Searching through a complex schema is relatively straight-forward in Swagger UI.
However, Swagger UI strips out some of the metadata that is present in the source files. For example, Guidewire-
proprietary tags are not rendered in Swagger UI. When you need access to all the metadata for an API, it may be
better to call the /openapi.json endpoint directly.
Note: Be aware that 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. For more information on
recommended request tools, see “Requests and responses” on page 24.
View an API definition using Swagger UI

Procedure
1. Identify the path for the API. (For a list of paths for each API, see “The base configuration system APIs” on
page 27.)
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
Result
The following screenshot shows the top of the Swagger UI display of the Common API.
Organization of 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 the appear in Swagger UI are for the entire Cloud API release.)
Every endpoint in the API appears in a list. For each API, the following information is shown by default:
• The endpoint's operation (such as GET)
• The endpoint's path (such as /activities)
• An endpoint summary (such as "Returns a list of activities assigned to the current user")
If you click the operation button, additional information about the endpoint appears. This includes:
• A more detailed endpoint description
• A list of query parameters supported by the endpoint
• A hierarchical list of resources and schemas used by the endpoint (This appears in the Responses section on the
Model tab.)
The API definition endpoints and Postman

In some situations, it is useful to view the raw API definition information. In Cloud API, every API includes two
endpoints that return the API definition: /openapi.json and /swagger.json.
• /openapi.json returns the API definition using the OpenAPI 3.0 specification, often referred to as "OpenAPI
3.0"
• /swagger.json returns the API definition using the Swagger 2.0 specification, often referred to as "Swagger
2.0"
Note: Cloud API is built using the Swagger 2.0 Specification. However, the definition for each API
can be returned in either the Swagger 2.0 specification (using the /swagger.json endpoint) or the
OpenAPI 3.0 specification (using the /openapi.json endpoint).
The API definition endpoints can be helpful when you want to view all metadata about an endpoint, including
metadata that 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.
From a metadata perspective, the OpenAPI 3.0 specification is richer. 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 an API definition using Postman

Before you begin
Install Postman. For more information and to download the tool, see https://www.postman.com/.
About this task

This task does not involve authentication information. This is because every type of caller can request API metadata,
including unauthenticated callers.
Procedure
1. Identify the path for the API. (For a list of paths for each API, see “The base configuration system APIs” on
page 27.)
3. Start Postman.
4. In Postman, start a new request by clicking the + tab to the right of the Launchpad tab.
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)
Result
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"
}
},
...
Organization of 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.
Beta APIs
Published APIs and endpoints
In future releases, system API functionality is expected to change. To help insurers manage potential future changes,
Guidewire maintains a Schema Backwards Compatibility Contract. This document identifies the rules for what
Guidewire is allowed to change in an API minor or maintenance release while still having that release considered to
be backwards compatible. To request a copy of the Schema Backwards Compatibility Contract, consult your
Guidewire representative.
The Schema Backwards Compatibility Contract applies to published APIs and endpoints. These APIs and endpoints
have been certified to be stable. By default, schema documentation resources (such as Swagger UI or the /
openapi.json endpoints) return only published APIs and endpoints.
Beta APIs and endpoints

Each release of Guidewire Cloud API may include one or more beta APIs or beta endpoints. A beta API and a beta
endpoint are an API or endpoint that is not yet covered by the Schema Backwards Compatibility Contract. These
APIs and endpoints have not been certified as stable. They may change in the future in ways beyond what is covered
by the Schema Backwards Compatibility Contract.
In the base configuration, beta APIs and endpoints:
• Are not enabled
• Are not returned by any schema documentation resources (such as Swagger UI or the /openapi.json endpoints)
Guidewire provides beta APIs and endpoints to help insurers with the development of system API functionality that
may be available in the future. However, Guidewire recommends using beta APIs and endpoints with caution. They
are not certified to be stable, and they are subject to change in future releases.
WARNING Guidewire does not support the use of beta APIs or beta endpoints in production.
Enabling beta APIs and endpoints

Every beta API or endpoint is controlled by a toggle in the config.properties file. A toggle is an expression in
config.properties that turns a feature on when the expression is set to true.
For some beta APIs and endpoints, the toggle is listed in config.properties, but it is set to false. For other beta
APIs and endpoints, there is no toggle in config.properties. To enable beta APIs and endpoints, you must either
set the existing toggle to true, or add a toggle to config.properties and set it to true. After you modify
config.properties in this way, you must restart the server.
For example, suppose that a release of Guidewire Cloud API included a fictitious set of beta endpoints that managed
insurance metrics. For these endpoints, the following toggle appears in config.properties:
feature.InsuranceMetricsApisBeta = false
To enable these endpoints, you would need to change the line to the following, and then restart the server:
feature.InsuranceMetricsApisBeta = true
Identifying beta APIs

The beta APIs and endpoints for this release, if any, are listed in the following section.
Once enabled, beta APIs and endpoints appear in the output of the /openapi.json and /swagger.json endpoints.
All beta APIs endpoints have the following attribute:
"x-gw-beta": true
For beta APIs, the x-gw-beta attribute is listed at the API level. The attribute does not appear at the endpoint level.
All endpoints in a beta API are considered beta endpoints.
For beta endpoints in a published API, the x-gw-beta attribute is listed with each endpoint.
The x-gw-beta attribute appears only for APIs and endpoints that are beta. Published APIs and published endpoints
do not have a listing of "x-gw-beta": false.
Once enabled, beta APIs also appear in Swagger UI. However, Swagger UI does not indicate whether a given API or
endpoint is beta.
WARNING Swagger UI does not render information from Guidewire proprietary tags, including
the x-gw-beta tag. This means that, once you enable beta APIs, Swagger UI does not distinguish
between published APIs and beta APIs. Guidewire strongly recommends that, if you enable beta
APIs on a given development instance, alert all developers using this instance to the fact that beta
APIs have been enabled. Without this alert, other developers may not be able to distinguish
between published APIs and beta APIs.
Beta APIs for this release

This release contains no APIs that are entirely beta. It also contains no beta endpoints in any of the published APIs.
Guidewire reserves the right to add new beta APIs and endpoints to future releases.
Routing related API calls 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 system API calls to be routed to different nodes.
This can cause problems, such as Concurrent Data Change Exceptions. Typically, multiple related system API calls
need to be routed to the same node.
There are two ways that you can ensure a series of related system API calls are routed to the same instance: session
IDs (which is the default behavior) and cookies.
Using session IDs

Within the context of system 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 Cloud Operations.
Using cookies
Within the context of system 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 Cloud Operations.
Comparing session IDs and cookies

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

chapter 3
GETs and response payload structures
This topic discusses how the GET operation queries for data and the structure of the response payload that contains
the query results. For information on how you can add query parameters to a GET to refine the query, see “Refining
response payloads using 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.
In its simplest format, a GET consists of the GET operation and the endpoint, such as GET /activities. A GET
can return either information about a single element (such as GET /activities/{activityId}) or information
about a collection (such as GET /activities/{activityId}/notes).
The response to a GET includes:
• An HTTP response code indicating success or failure.
• A response payload that contains the data that was queried for.
When a developer configures a caller application to query information using a GET, the construction of the API call
is fairly straight-forward. The call may require query parameters, but GETs do not require a request payload.
The majority of the work lies in parsing the response payload. The remainder of this chapter discusses how response
payloads are structured and how developers can learn about response payload formats.
Standardizing payload structures

Communication between caller applications and system APIs is easier to manage when the information in the
payloads follows a standard structure. The system APIs have 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 the system APIs. To maintain a standard
payload structure, the system APIs use two data envelopes: DataEnvelope and DataListEnvelope.
GETs and response payload structures 35
DataEnvelope is used to standardize 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 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)
• total
The format of a payload for a collection looks like:
{
"count" ...,
"data": [
{ properties_for_element_1 },
...
],
"links": ...,
"total": ...
}
Every property does not appear in every payload. There are different reasons why a property may not appear in a
given payload. For example:
• Some properties, such as refid, apply only to requests and do not appear in response payloads.
• Some properties, such as count, apply only to responses and do not appear in request payloads.
• Some properties, such as related, do not appear by default and appear only when the request includes certain
query parameters.
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, the system APIs also use 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.
36 chapter 3: GETs and response payload structures
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 response schemas

You can use Swagger UI to review the structure of a response payload for a given endpoint. This includes the
hierarchy of response schemas and the type of information in each schema. The information appears in each
endpoint's Responses section on the Model tab.
View a response schema in Swagger UI

Procedure
2. In a web browser, navigate to the Swagger UI for the appropriate API.
• For more information, see “View an API definition using Swagger UI” on page 29.
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 24.

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.
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.
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 25.
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": {
"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 include
any included resources. Included resources are discussed in “Payload structure for a response with included
resources” on page 43.
Examples of response payloads in Postman
You can use the following Postman calls to load examples of response payloads. All of these calls assume the
following:
• Your instance of PolicyCenter is installed on your local machine.
• The Large sample data has been loaded.
• The call uses basic authentication with user aapplegate and password gw.
Response payload examples
Response payload for a single resource:

1. Activity "Verify coverage" (whose Public ID is pc:101)
• GET http://localhost:8180/pc/rest/common/v1/activities/pc:101
2. Policy 0596932432 (whose Public ID is pc:1)
• GET http://localhost:8180/pc/rest/policy/v1/policies/pc:1
Response payload for a collection:
1. All activities assigned to Alice Applegate
• GET http://localhost:8180/pc/rest/common/v1/activities
2. All policies assigned to Alice Applegate
• GET http://localhost:8180/pc/rest/policy/v1/policies
Structure of a basic response

The high-level structure of a basic response is shown below. The first and last properties (count and collection-level
links) are used only for collection payloads. All other properties are used for both element and collection payloads.
(Note: JSON does not support comments. However, to clarify the code, pseudo-comments have been added. Each
pseudo-comment is preceded by a hashtag (#).)
{
"count": N, # Number of resources in collection*
"data": [ # List of resources
{ # Resource 1 begins here
"attributes": { # Resource 1 name/value pairs
"propertyName": "propertyValue",
... },
"checksum": "val", # Resource 1 checksum value
"links": { ... } # Resource 1 links
}, # Resource 1 ends here
... },
"links": { ... } # Resource 2 links
... ], # Resources 3 to N
"links": { ... } # Collection-level links*
}
# *-used only for collection responses
The count property

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

The data section

The data section contains information about the resources returned by the endpoint. For each resource, the
following subsections appear by default:
• attributes - A set of name/value pairs for the fields of each resource.
• checksum - A checksum value for each resource.
• links - HTTP links that can be used to take action on each resource.
If an endpoint returns a single resource, 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 “Specifying which fields to GET” on page 52.
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, the system APIs require 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. The system APIs behave this
way in 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,
...
},
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 “Specifying which fields to GET” on page 52.
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": {
},
"assignedUser": {
},
Complex references are references to a related object that uses a schema more complex than the
SimpleReferences schema. For example, when a contact's primary address is added to a response payload, it uses
the Address schema, which includes a larger number of fields.
Fields with null values are omitted

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

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

The links subsection of the data section lists paths that identify actions that can be taken on the specific element, if
any. Each link has a name, an href property, and a list of methods. Caller applications can use these links to
construct HTTP requests for additional actions to take on that resource.
Note: The links subsection of the data section is one of the way in which Cloud API enforces the
Hypermedia as the Engine of Application State (HATEOAS) constraint.
For example, suppose that a given caller application gets activity xc:20. This application has sufficient permission to
assign this activity and to view the notes associated with this activity. The following would appear in the links
section for activity xc:20:
"links": {
"assign": {
"href": "/common/v1/activities/xc:20/assign",
"methods": [
"post"
]
},
"notes": {
"href": "/common/v1/activities/xc:20/notes",
"methods": [
"get",
"post"
]
},
"self": {
"href": "/common/v1/activities/xc:20",
"methods": [
"get"
]
}
}
The self link is a link to the resource itself. The self link is useful when a caller application receives a list of
resources and wants to navigate to a specific resource in the list.
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 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 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.
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 Where do their fields When do they appear?
type resources for each primary appear?
resource?
Inlined Typically one. (For Entirely in the attributes If the query does not use the fields query parameter,
resource example, every activity has section of the root then each inlined resource appears only if it is one of
only one related resource the default attributes.
assignedUser.) 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 parame-
ter.
Included One to many. (For IDs appear in the related When the query parameter includes the ?
resource example, every activity section of the root include=resourceName query parameter
can have several related resource. The remaining
notes.) attributes appear in the
included section at the
bottom of the payload.
Tutorial: Send a Postman request with included resources

Tutorial steps
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.
• 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
... },
"links": { # Links relevant to Resource 1
... },
"related": { # List of resources related to R1
"resourceType": { # Related resource type
"count": NN, # Number of related resources for R1
"data": [
{ # First resource related to R1 starts
"id": "relatedResourceID",
"type": "resourceType"
}, # First resource related to R1 ends
... # Other resources related to R1
] } }
"attributes": { # Recourse 2 name/value pairs
... },

"links": { # Links relevant to Resource 2

... },
"related": { # List of resources related to R2
"resourceType": { # Related resource type
"count": NN, # Number of related resources for R2
"data": [
{ # First resource related to R2 starts
"id": "relatedResourceID",
"type": "resourceType"
}, # First resource related to R2 ends
... # Other resources related to R2
] } }
... ], # Resources 3 to N
"links": { # Links relevant to collection
...
},
"included": { # List of related resources
"resourceType": [ # First related resource type
{
"attributes": { # Related resource 1 start
... # Related resource 1 name/value pairs
"id": " relatedResourceID ",
... },
"checksum": "0", # Related resource 1 checksum value
"links": { ... } # Links relevant to Related resource 1
},
... # Related resources 2 to end
] }
}
The related section (for a resource)

For every resource, there is an additional related section that identifies:
• The number of included resources, and
• The IDs of the included resources
For example, the following code snippet is from the response for a query for all activities and related notes. Activity
xc:44 has one included note, whose ID is xc:55.
{
"attributes": {
...
"id": "xc:44",
...
"subject": "Check coverage"
},
"checksum": "2",
"links": {
...
},
"related": {
"notes": {
"count": 1,
"data": [
{
"id": "xc:55",
"type": "Note"
}
]
}
}
},
If a GET uses the included query parameter, but no related resources exist, the related section still appears. But,
the count is 0 and the data section is empty. For example:
"related": {
"notes": {
"count": 0,
"data": []
}
}

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

For every response, there is an included section that appears at the end of the response payload. It lists details about
every included resource for the primary resources.
For example, the following code snippet is from the included section from the previous example.
"included": {
"Note": [
{
"attributes": {
"author": {
"displayName": "Betty Baker",
},
"bodySummary": "Main contact is on vacation 03/20",
"confidential": false,
"createdDate": "2020-03-30T23:11:33.346Z",
"id": "xc:55",
"securityType": {
"code": "unrestricted",
"name": "Unrestricted"
},
"subject": "Main contact is on vacation 03/20",
"topic": {
"code": "general",
"name": "General"
},
"updateTime": "2020-03-30T23:12:08.892Z"
},
"checksum": "0",
"links": {
"self": {
"href": "/common/v1/notes/xc:55",
"methods": [
"get",
"patch"
]
}
}
}
]
},
Recall that activity xc:44 has one included note. The included note's ID is xc:55. The note shown in the included
section is the note related to activity xc:44.
Including either a collection or a specific resource

For a given endpoint, some of the include options return a collection of resources for each primary resource. Other
include options return a single resource for each primary resource.
An example of the first case is GET /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, you can determine the resources that can be included by referring to the Swagger UI model for
the endpoint. There will be a data envelope in the model whose name ends with ...Inclusions. This data envelope
lists all the resources that can be included when querying for that type of resource.
For example, in the Common API, the model for GET /activities references an ActivityResponseInclusions
element. This element has a single child element - Note. This means that the only type of element you can include
on an activity query is notes.
If you attempt to include a resource type that a given endpoint does not support for inclusion, the API returns a 400
error code and message. For example, the following is the message if you attempt to do a GET /activities?
include=users:
"userMessage": "Bad value for the 'include' query parameter - The requested
inclusions '[users]' are not valid for this resource. The valid options are [notes]."


chapter 4
Refining response payloads using

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.
• “Tutorial: Send a GET with the filter parameters” on page 52
• “Tutorial: Send a GET with the fields parameter” on page 55
• “Tutorial: Send a GET with the sort query parameter” on page 56
• “Tutorial: Send a GET with the pageSize and totalCount parameters” on page 59
• “Tutorial: Send a GET with query parameters for included resources” on page 61
Overview of query parameters

When you execute a system API call using only the endpoint (as in GET /activities), the response payload has a
default set of resources and a default structure.
You may want to refine the response payload beyond the default behavior by:
• Specifying a custom set of properties.
• Filtering out resources that do not meet a given criteria
• Sorting the resources
• Limiting the number of elements returned in each payload
• Retrieving a count of the total number of resources in the database that meet the query's criteria
You can refine the response payload using query parameters. A query parameter is an expression added to the HTTP
request that modifies the default response payload.
A system API call can include any number of query parameters. The list of query parameters starts with a question
mark (?). If there are multiple query parameters, each is separated by an ampersand (&). For example:
• GET /activities?fields=*all
• GET /activities?filter=escalated:eq:false
• GET /activities?fields=*all&filter=escalated:eq:false
Included resources
You can use the include query parameter to include resources related to the primary resources of the response. You
can also use query parameters to specify a custom set of properties for included resources, filter out included
Refining response payloads using query parameters 49
resources that do not meet a given criteria, sort the included resources, and so on. For more information, see “Using
query parameters on included resources” on page 59.
Viewing query parameter documentation in Swagger UI

For every endpoint, Swagger UI provides descriptions of the query parameters supported by that endpoint. This
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.
Query parameter error messages

If you attempt to use a query parameter on a field that does not support that parameter, the system API returns a 400
Bad Request error and an error message. For example, if you execute: GET /activities?sort=escalationDate,
the system API provides the following error message:
"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."
Specifying the resources and fields to return

You can use query parameters to:
• Specify filtering criteria to narrow which resources are returned
• Specify which fields you want returned for the resources that are returned
Filtering GETs
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 ?filter=escalated:eq:true ...the escalated field equals true
ne Not equal ?filter=escalated:ne:true ...the escalated field equals false
lt Less than ?filter=dueDate:lt: ...the due date is less than (before) May
2020-05-11T07::00::00.000Z 11, 2020.
gt Greater than ?filter=dueDate:gt: ...the due date is greater than (after) May
2020-05-11T07::00::00.000Z 11, 2020.
50 chapter 4: Refining response payloads using query parameters

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 ?filter=dueDate:ge: ...the due date is greater than or equal to
equal 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%20claimant ...the subject starts with the string
"Contact claimant"
cn Contains ?filter=subject:cn:Contact%20claimant ...the subject contains the string "Contact
claimant"
The query parameter is passed as part of a URL. Therefore, special conventions must be used for certain types of
values 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::Information%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.
References to typekey fields automatically resolve to the field's code. For example, to filter on activities whose
priority is set to urgent, use: GET /activities?filter=priority:eq:urgent.
You can also use the filter query for related resources added through the include parameter. For more information,
see “Using query parameters on included resources” on page 59.
Determining which values you can filter on

For a given endpoint, you can identify the attributes that are filterable by reviewing the endpoint Model in Swagger
UI. If a field is filterable, then the schema description of the field includes the text: "filterable": 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 "filterable": true expression, but the escalationDate field does
not. This means that you can filter on escalated, but not escalationDate.
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 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
Endpoints with default filters

Some endpoints have default filters. For example, the /accounts/{AccountID}/jobs endpoint has a default filter
that returns only open jobs.
You can identify whether an endpoint has a default filter by checking the endpoint summary in Swagger UI. The
summary is visible after you click the GET button in Swagger UI for the given endpoint.
For example, the summary for the /accounts/{AccountID}/jobs endpoint says: "Retrieve a list of jobs associated
with this account. By default this will include only open jobs."
You can use the filter query parameter to override default filters. For example, the following GET returns all jobs
without regards to the status: GET /accounts/{AccountID}/jobs?filter=jobFilter:eq:all
If you add a filter query parameter on an endpoint with a default filter, the default filter is discarded. If you want
the response payload to reflect both the default filter and a custom filter, you must specify both explicitly.
Tutorial: Send a GET with the filter parameters

Tutorial steps
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.
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.
Specifying which fields to GET

Every endpoint returns a default set of fields. You can override this default set using the fields 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 “Using query parameters on included resources” on page 59.)
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 as it returns fields that cost additional
resources trimmed from default response payloads; instead, use the *default filter with any
specific fields that do not appear in the default detail or summary list.
• *default - Return the default fields (typically used in conjunction with an additional field list)
• field_list - Return one or more fields specified as a comma-delimited list
The set of fields returned by default

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 fields for a contact resource (for example, the default fields for
the /accounts/{accountId}/contacts/{contactId} endpoint) and the summary fields returned for a contact
collection (for example, the default fields for the /accounts/{accountId}/contacts endpoint). Fields included in
the Detail only are in bold:
• Detail: companyName, contactSubtype, displayName, emailAddress1, emailAddress2, id, industryCode,
primaryPhoneType, subtype, taxId
• Summary: companyName, contactSubtype, displayName, emailAddress1, id, industryCode, subtype, taxId
The fields parameter has three options related to these default sets:
• *detail - Returns the fields in the detail list
• *summary - Returns the fields in the summary list
• *default - Returns the fields in the detail list (if the endpoint returns a single element) or the fields in the
summary list (if the endpoint returns a collection)
For endpoints that return a single element:
• ?fields=*default and ?fields=*detail are logically equivalent.
• You can override the default behavior by using ?fields=*summary, which returns the summary fields instead of
the detail fields.
For endpoints that return a collection:
• ?fields=*default and ?fields=*summary are logically equivalent.
• You can override the default behavior by using ?fields=*detail, which returns the detail fields instead of the
summary fields.
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.
Returning the default properties plus additional specific properties

To return the default fields of an endpoint with an additional set of fields, use:
?fields=*default,field_list
where field_list is a comma-delimited list of fields.

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

To return a specific set of fields, use:
?fields=field_list

where field_list 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
snippet of the response for a GET /activities. This payload contains two inline resources, assignedGroup and
assignedUser.
"attributes": {
"activityPattern": "contact_claimant",
"assignedGroup": {
},
"assignedUser": {
},
"closeDate": "2020-04-06T07:00:00.000Z",
"dueDate": "2020-04-06T07:00:00.000Z",
"escalated": false,
"id": "cc:20",
...
}
You can use the fields query parameter to specify an inlined resource. When you do, all default fields for that
resource are returned. For example, you could specify that you want a GET /activities to return only the
assignedGroup and assignedUser fields (and all of their default subfields) using the following:
GET /activities?fields=assignedGroup,assignedUser
This would return:
"attributes": {
"assignedGroup": {
},
"assignedUser": {
}
}
You can also specify specific subfields using the following syntax:
?fields=inlinedResourceName.fieldName
For example, you could specify that you want a GET /activities to return only the IDs of the assigned user and
group using the following:
GET /activities?fields=assignedGroup.id,assignedUser.id
This would return:
"attributes": {
"assignedGroup": {
},
"assignedUser": {
}
}
Returning all properties

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.
Tutorial: Send a GET with the fields parameter

Tutorial steps
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 id and subject fields.
Getting resources "as of" a certain date

In some situations, a system 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 /policies/pc:10?asOfDate=2019-01-01
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".
Sorting the result set

For endpoints that return collections, you can sort the elements in the collection. To do this, use:
?sort=properties_list
where properties_list is a comma-delimited list of properties that support sorting for that endpoint.
For example, the following query returns all activities assigned to the current caller 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
“Using query parameters on included resources” on page 59.
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.
Tutorial: Send a GET with the sort query parameter

In this tutorial, you will execute two requests to GET activities. The first does not sort the responses. The second
does. To make it easier to compare the order of activities, each request retrieves only the ID and due date of each
activity.
Tutorial steps
GET http://localhost:8180/pc/rest/common/v1/activities?fields=id,dueDate
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.
Controlling pagination
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. A caller can use "previous" and "next" links to access
additional payloads with the previous or next "page" of N resources. The practice of separating a list of resources
into discrete groups that can be paged through 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.
Limiting the number of resources per payload

GETs that return collections typically return multiple root resources. You can use the pageSize parameter to limit
the number of root resources returned in a given payload. This can be useful when a query may return more
resources than what is practical for performance and parsing. To limit the number, use the following syntax:
pageSize=n
where n is the maximum number of resources per payload to return. 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.0apiconfig.yaml,
the AccountActivityPatterns resource overrides the default values and uses defaultPageSize=100 and
maxPageSize=500.)
You can also use the pageSize query for related resources added through the include parameter. For more
information, see “Using query parameters on included resources” on page 59.
Selecting a single resource in a collection

When a response payload contains a collection, every element in the collection is listed in the data section of the
payload. For every element, there is a links section that contains endpoints relevant to that element. One of the
links is the self link. For example:
{
"attributes": {
...
"id": "cc:32",
... },
...
"links": {
...
"self": {
"href": "/common/v1/activities/cc:32",
"methods": [
"get",
"patch"
]
}
}
}
The href property of the self link is an endpoint to that specific element. When necessary, you can use this link to
construct a call to act on that element.
Paging 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 N elements.
◦ This appears for all collections.
• The prev link is an endpoint to 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 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 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, the system APIs use a pageOffset parameter. This
parameter is used in the prev and next links for a collection. The pageOffset index starts with 0, so a theoretical
pageOffset=0 would start with the first element and pageOffset=5 skips the first 5 elements and starts with the
sixth.
There can be some complexity involved in determining how to construct a link with the correct pageOffset value.
Therefore, Guidewire recommends that you use the prev and next provided in response payloads and avoid
constructing pageOffset queries of your own.
Retrieving 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 payload.
• 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. If a total value is equal
to 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.
You can also use the includeTotal query for related resources added through the include parameter. For more
information, see “Using query parameters on included resources” on page 59.
Tutorial: Send a GET with the pageSize and totalCount parameters

Tutorial steps
GET http://localhost:8180/pc/rest/common/v1/activities?pageSize=10&includeTotal=true
Checking your work

Compare the two payloads. In the first payload, the count of activities included in the payload is 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.)
Using query parameters on 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 43.
Most query parameters that can be used on primary resources can also be used on included resources.
Specifying query parameters that apply to an included resource

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

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

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

The filter parameter
You can filter out included resources that do not meet a given criteria.
• Syntax: filter=resource:field:op:value
• Example:
GET 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 fields parameter

You can specify which fields you want returned in the included resources.
• Syntax: fields=resource:field_list
• Example:
include=contacts&
fields=contacts:licenseState,licenseNumber
• Returns: Policy pc:10 and its included contacts. For the contacts, return only licenseState and
licenseNumber.
The sort parameter

You can sort the included resources. This sorting is reflected in both the payload's related sections and the
included section.
• Syntax: sort=resource:properties_list
• Example:
include=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:
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:
include=contacts&
includeTotal=contacts:true
• Returns: Policy pc:10, its included contacts, and the total number of included contacts for pc:10.
Tutorial: Send a GET with query parameters for included resources

Tutorial steps
GET http://localhost:8180/pc/rest/policy/v1/policies?include=contacts
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).

chapter 5
POSTs and request payload structures
This topic discusses the POST operation 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 81.
• “Tutorial: Create a new note that specifies required fields only” on page 70
• “Tutorial: Create a new note that specifies optional fields” on page 70
Overview of POSTs
A POST is a system API operation that creates a resource or a set of related resources in PolicyCenter. The POST
operation is also used to execute specific business processes, such as assigning an activity.
A POST consists of the POST operation 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 contains 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 to a system 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 completes an activity 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 and request payload structures 63

Standardizing payload structures

Communication between caller applications and system APIs is easier to manage when the information in the
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 the system APIs. To maintain a standard
payload structure, the system APIs use two data envelopes: DataEnvelope and DataListEnvelope.
DataEnvelope is used to standardize the format of information for a single element. It specifies a data property with
the following properties: checksum, id, links (for a single element), method, refid, related, type and uri. At a
high level, the format of a payload for a single element looks like:
{
"data": {
"checksum": ...,
"id": ...,
"links": ...,
"method": ...,
"refid": ...,
"related": ...,
"type": ...,
"uri": ...
}
}
}
DataListEnvelope is used to standardize the format of information for collections. It specifies the following
properties, which are siblings to the data section: count, links (for a collection), and total. At a high level, the
format of a payload for a single element looks like:
{
"count" ...,
"data": [
...
],
"links": ...,
"total": ...
}
Every property does not appear in every payload. There are different reasons why a property may not appear in a
given payload. For example:
• Some properties, such as refid, apply only to requests and do not appear in response payloads.
• Some properties, such as count, apply only to responses and do not appear in request payloads.
• Some properties, such as related, do not appear by default and appear only when the request includes certain
query parameters.
Standardizing information specific to a given endpoint

DataEnvelope and DataListEnvelope provide a standard format for information that is applicable to all request
and response payloads. But, different endpoints interact with different types of resources. For each endpoint, some
portion of the payload must provide information about a specific type of resource.
To address this, the system APIs also use 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.
64 chapter 5: POSTs and request payload structures
Request and response schemas also define an attributes property for the payload. This property is associated with
a schema that includes resource-specific information for the payload. For example, the GET /activity/
{activityId} endpoint specifies an attributes property in the ActivityData child schema. This property is
associated with the Activity schema, which contains activity-specific fields, such as activityPattern and
activityType. As a result, response payloads for the GET /activity/{activityId} endpoint have this structure:
{
"data": {
"checksum": ...,
"attributes" : {
"activityPattern": ... ,
"activityType": ...,
...},
"id": ...,
"links": ...,
"method": ...,
"refid": ...,
"related": ...,
"type": ...,
"uri": ...
}
}
}
Viewing request schemas

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

Procedure
2. In a web browser, navigate to the Swagger UI for the appropriate API.
• For more information, see “View an API definition using Swagger UI” on page 29.
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 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
Determining the required, optional, and write-only fields

Within the context of a request payload, each field of a given resource is either:
• Required - This field must be included.
• Optional - This field can be included or omitted.
• Read-only - This field cannot be included.

Required fields
A required field must be included in the request payload. A field can be required for one of several reasons:
• The field is marked as required on the associated schema, and therefore must be included on all POSTs using that
schema.
• The field is not marked as required on the associated schema, but it is always required by PolicyCenter. (For
example, the underlying database column could be marked as non-nullable with no default and the application
does not generate a value for it.)
• The field is not required by the API, but it is sometimes required by PolicyCenter. (For example, there could be a
validation rule in PolicyCenter that says non-confidential documents do not require an author, but confidential
documents do. Therefore, the author field is required only some of the time.)
Whether a field is required or allowed in a POST does not always match the requiredness of the corresponding data
model entity or database column. For example:
• A field may be marked as non-nullable in the database (and therefore "required"). But, PolicyCenter always
generates a value for it. Therefore, the field is marked as read-only and not required in the API schema.
• A field may be marked as non-nullable in the database (and therefore "required") and required when an object is
created. But once the object is created, the value of the field cannot be changed. Therefore, the field is required
for creation, but read-only for updates.
Determining that a field is required by the API

If a field is required by the API, the schema specifies the following property for the field:
"requiredForCreate": true
For example, the Claim API has a POST claim/{claimId}/contacts endpoint that creates a contact for a given
claim. One of the data envelopes used by this endpoint to define the request schema is the ClaimContact schema. It
contains the following:
contactSubtype string
x-gw-type: typekey.Contact
x-gw-extensions: OrderedMap { "createOnly": true,
"requiredForCreate": true }
dateOfBirth string($date)
x-gw-nullable: true
x-gw-extensions: OrderedMap { "before": "now",
"entitySubtype": "Person" }
Note that the contactSubtype field has the "requiredForCreate": true property, whereas the dateOfBirth field
does not. This means that the API requires a contact subtype for contact creation, but not a date of birth.
Determining that a field is required by the application

If a field is not required by the API but is required by the application, the only way to identify this is to send a
request to the application. If there is a required value that is missing from the request payload, you will get a
BadInputException response with a message identifying the missing fields. For example:
{
"status": 400,
"errorCode": "gw.api.rest.exceptions.BadInputException",
"userMessage": "The 'body' field is required when creating notes"
}
Read-only fields
Read-only fields are fields that are set within the application (either by a user or by application logic) and cannot be
set or modified by system API calls. Read-only fields are listed in the request schema as readonly: true. You can
view this information in Swagger UI from the endpoint's Model tab.
For example, this is the Model text for the POST /activity/{activityId}/notes endpoint's createDate field:
createdDate string($date-time)
readOnly: true

You cannot include read-only values in a request payload. If you do, the API returns a BadInputException with an
error message such as:
"message": "Property 'createdDate' is defined as read-only and cannot be specified on inputs"
Optional fields
From a technical perspective, any field that is neither required nor read-only is optional. These fields can be either
include or omitted as appropriate.
Request payload structure

The basic structure for a request payload that creates a single resource is:
{
"data":
{
"attributes": {
<field/value pairs are specified here>
}
}
}
For example, this request payload could be used to create a note:

{
"data":
{
"attributes": {
"subject": "Main contact vacation",
"body": "Rodney is on vacation for the entire month of June.
During this time, direct any questions to Sarah Jackson.",
"topic": {
"code": "general"
}
}
}
}
In some situations, you can create an object using an "empty body" (a body that specifies no values). An object
created in this way will contain only default values. In these situations, the payload has an empty attributes
section:
{
"data":
{
"attributes": {
}
}
}
Specifying scalar values in a request payload

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.
On a schema, field value types for scalar values are marked using the type property. In request payloads, scalar
values follow these patterns:
Field value type Pattern Example Notes

String "fieldName" : "value" "firstName" : "Ray", IDs are considered strings.
"id": "demo_date:12"
Integer "fieldName" : value "numDaysInRatedTerm": 180 Unlike the other scalar value types,
integer, Boolean, and null values are
expressed without quotation marks.


Decimal "fieldName" : "value" "speed": "60.0"
Date "fieldName" : "value" "dateReported": Expressed using the format

"2020-04-09" YYYY-MM-DD
Datetime "fieldName" : "value" "createdDate": Expressed using the format
"2020-04-09T18:24:57.256Z" YYYY-MM-DDT
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.
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 objects in a request payload

The syntax for specifying an object is:
"objectName": {
"field1": value_or_"value",
"field2": value_or_"value",
...
}
For example:
"assignedUser": {
"isActive": true
}
The value of each object's field either uses or does not use quotation marks based on the datatype of the field. (For
example, assignedUser has a displayName field. The value for this field is a string, so the value is specified in
quotes. If assignedUser also had an isActive field, which was a Boolean, the value would be specified as either
true or false without quotes.
Typekeys and money values are expressed in objects. Each of these are specified using a standard pattern.
Typekeys
Typekeys use the following format:
"field": {
"code": "value"
}
For example:
"priority": {
"code": "urgent"
}
Typekeys also have a name field, which is included in responses. But, the name field is not required. If you include it
in a request schema, it is ignored.
Monetary amounts
Monetary amounts use the following format:
"field": {
"amount": "amountValue",

"currency": "currencyCode"
}
For example:
"transactionAmount": {
"amount": "500.00",
"currency": "usd"
}
Related objects
For information on how to specify related objects in a request payload, see “Request inclusion” on page 95.
Setting values and objects to null

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

Field whose value is "fieldName" : null "middleName": null You can set any scalar value to null.
to 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 or currency amount to null, specify the null at the field level. (Do not specify the null at
the amount and currency 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 24.
Send a POST using Postman

Procedure
3. Under the Untitled Request label, make sure that POST is selected.
• 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
5. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the request payload into the text field underneath the radio buttons.
6. Click Send. The response payload appears below the request payload.
Tutorial: Create a new note that specifies required fields only

In this tutorial, you will create a note whose subject is "API tutorial note 1" for an existing activity. The other fields
will not be specified and will be assigned default values by the application (such as not being confidential and
having a subject of "General").
Tutorial steps
2. 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>.
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
d. Paste the following into the text field underneath the radio buttons.
{
"data":
{
"attributes": {
"body": "API tutorial note 1"
}
}
}
Checking your work

1. View the new note in 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 should be 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

In this tutorial, you will create a note whose subject is "API tutorial note 2" for an existing activity. You will also
specify values for two optional fields: confidential (set to true) and subject (set to "Legal").
Tutorial steps
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>.
POST http://localhost:8180/pc/rest/common/v1/activities/<activityId>/notes
{
"data":
{
"attributes": {
"body": "API tutorial note 2",
"confidential": true,
"topic": {
"code": "legal"
}
}
}
}
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 should be 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.

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

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 operations (Create, Read, Update, Delete). Like other REST APIs,
Cloud API exposes these CRUD operations through endpoints that support the POST, GET, PATCH, and DELETE
operations.
However, in some circumstances, a system API needs to trigger a business process that does not readily map to a
single Create, Read, Update, or Delete operation. For example, the system APIs expose 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 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 operation.
• 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 guide.
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 the system APIs, 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 107.
Improving POST performance

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

chapter 6
PATCHes
This topic discusses the PATCH operation, which modifies existing data.
• “Tutorial: PATCH an activity” on page 77
Overview of PATCHes
A PATCH is a system API operation that modifies an existing resource or a set of related resources in PolicyCenter.
A PATCH consists of the PATCH operation 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 a system 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. The system APIs support 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 system APIs is easier to manage when the information in the
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 64.
PATCHes 75
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 65.
PATCHes and arrays

You can include arrays in a PATCH request payload. Within the system APIs, 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 24.
Send a PATCH using Postman

Procedure
3. Under the Untitled Request label, make sure that PATCH is selected.
• 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
76 chapter 6: PATCHes

• In the first row of tabs (the one that starts with Params), click Body.
• In the row of radio buttons, select raw.
• At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
• Paste the request payload into the text field underneath the radio buttons.
Tutorial: PATCH an activity

In this tutorial, you will find an open activity from the sample data. You will then update the activity's subject and
priority.
Tutorial steps
2. The sample data includes one "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
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>
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"
}
}
}
}
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.
PATCHes 77
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 "!".
Responses to a PATCH
Every successful PATCH generates a response object with a response payload. Depending on the default fields
returned and whether any query parameters have been specified, the response payload may or may not contain the
values modified by the PATCH.
Similarly to request schemas, response schemas follow certain patterns around using data envelopes to wrap the
resource schema. In many instances, the request and response schemas will match.

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

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

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.
PATCH. This can cause a lost update. Within the system APIs, a lost update is a modification made to a resource
that unintentionally overwrites changes made by some other process.
page 107.
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.
78 chapter 6: PATCHes
chapter 7
DELETEs
This topic provides an overview of DELETEs, which are used to delete resources.
• Tutorial: “Tutorial: DELETE a note” on page 79
Overview of DELETEs
Within the context of true REST APIs, 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 system API operation 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 operation and the endpoint, such as DELETE /notes/{noteId}. Similar
to GETs, DELETEs are not permitted to have a request payload.
The response to a DELETE includes an HTTP code indicating success or failure. DELETE responses do not have a
response payload.
Tutorial: DELETE a note

In this tutorial, you will send calls as 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 79
Tutorial steps
%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 tab.
a. On the Authorization tab, select Basic Auth using user aclinton and password gw.
a. POST http://localhost:8180/pc/rest/common/v1/activities/<activityId>/notes
{
"data":
{
"attributes": {
"body": "API tutorial note to be deleted"
}
}
}
7. Click Send. In the response payload, identify the note's id.

8. Open a third request tab and right-clicking the second tab and selecting Duplicate Tab tab.
a. Because it is a duplicate of the second tab, this tab also uses user 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

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.
DELETE. This can cause a lost update. Within the system APIs, a lost update is a modification made to a resource
that unintentionally overwrites changes made by some other process.
page 107.
80 chapter 7: DELETEs
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 discusses these features in detail.
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, request inclusion, and batch requests.
Composite requests are requests which consist of multiple sibling subrequests, with no parent request. Each
subrequest is executed transactionally in the order it appears. If a given subrequest that attempts to commit data
fails, the entire composite request fails. Information can be passed from one subrequest to another.
For details about composite requests, see “Composite requests” on page 83.
Request inclusion is a technique for POSTs and PATCHes in which the call consists of the following:
• A single parent request that creates or modifies a resource
• One or more child requests that create or modify resources related to the parent resource
If either the parent request or any child request fails, the entire request fails.
For details about request inclusion, see “Request inclusion” on page 95.
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 101.
Comparing features that execute multiple requests

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

Feature Composite requests Request inclusion Batch requests

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

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

chapter 9
Composite requests
From a Cloud API perspective, a composite request is a set of requests that are executed in a single InsuranceSuite
bundle (which corresponds to a single database transaction).
• A composite request can include one or more subrequests that create or modify data. Either all of the subrequests
succeed, or none of them are executed. Each subrequest is a separate unit of work.
• A composite request can also include one or more subselections that query for data.
Subrequests and subresponses are executed serially, in the order they are specified in the composite request payload.
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 are limited to a maximum number of subrequests. For more information, see “Configuring the
maximum number of subrequests” on page 92.
Constructing composite requests

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

A composite request can have up to two sections:
• A requests section, which contains the subrequests that commit data.
• A selections section, which contains the subselections that query for data. These are executed after the
subrequests, and only if all the subrequests commit data successfully.
At a high level, the syntax for these sections is as follows:
{
"requests": [
{
Composite requests 83
<subrequest 1>
},
{
<subrequest 2>
},
...
],
"selections": [
{
<subselection 1>
},
{
<subselection 2>
},
...
]
}
The requests section

In the requests section, the only supported operations are POST, PATCH, and DELETE. This includes both POSTs
that create data and POSTs that execute business actions (such as POST /assign).
The basic syntax for the requests section is shown below.
{
"requests": [
{
"method": "<post/patch/delete>",
"uri": "<path>",
"body": {
"data": {
"attributes": {
"<field1>": "<value1>",
...
}
}
}
},
{
<next subrequest>
},
...
{
<final subrequest>
}
]
}
For example, the following simple composite request creates two notes for activity xc:202.
POST <applicationURL>/rest/composite/v1/composite
{
"requests": [
{
"method": "post",
"uri": "/common/v1/activities/xc:202/notes",
"body": {
"data": {
"attributes": {
"body": "Cloud API note #1."
}
}
}
},
{
"method": "post",
"body": {
"data": {
"attributes": {
}
}
}
84 chapter 9: Composite requests

}
]
}
For the complete syntax that includes all composite request features, see “Complete composite request syntax” on
page 93.
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 a value from the subrequest's response payload as a JSON path expression.
For example, suppose a subrequest that creates an activity has the following:
"vars": [
{
"name": "newActivityId",
"path": "$.data.attributes.id"
}
]
This creates a variable named newActivityId, which is set to the value of the data section's attributes section's
id field (which would typically be the ID of the newly created activity).
Referencing variables
To reference a variable, use the following syntax:
${<varName>}
You can use variables anywhere in the body of a subrequest. The most common uses for variable values are:
• In an attributes field
• Within the path of a uri
• As part of a query parameter
For example, suppose there is a subrequest that creates an activity, and it is followed by a subrequest that creates a
note. The first subrequest creates a newActivityId variable as shown previously. The uri for the second subrequest
is:
"uri": "/common/v1/activities/${newActivityId}/notes"
This would create the new note as a child of the first subrequest's activity.
The following is the complete code for the previous examples.
{
"requests": [
{
"method": "post",
"uri": "/account/v1/accounts/pc:34/activities",
"body": {
"data": {
"attributes": {
"activityPattern": "contact_insured",
"subject": "Cloud API activity"
}
}
},
"vars": [
{
}
]
},
{
"method": "post",
"uri": "/common/v1/activities/${newActivityId}/notes",
"body": {
"data": {
"attributes": {
}
}
}
}
]
}
Responses to the subrequests

The response to a composite request contains a responses section. This section contains one subresponse for each
subrequest. Every subresponse has three sections:
• A body section, which by default contains the default response data defined in the corresponding endpoint.
• A headers section, which contains any custom headers.
• A status field, which indicates the subresponse's status code.
For example, the following is the responses section and the first subresponse for a composite request whose first
subrequest created an activity:
"responses": [
{
"body": {
"data": {
"attributes": {
"activityType": {
"code": "general",
"name": "General"
},
"assignedByUser": {
"id": "demo_sample:1",
"type": "User",
"uri": "/admin/v1/users/demo_sample:1"
},
...
},
"checksum": "0",
"links": {
"assign": {
"href": "/common/v1/activities/cc:403/assign",
"methods": [
"post"
]
},
...
}
}
},
"headers": {
"GW-Checksum": "0",
"Location": "/common/v1/activities/xc:403"
},
"status": 201
},
Fields whose values are generated when data is committed

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

In some cases, a given object may be modified by multiple subrequests. This makes the intermediate subresponses
unnecessary, and those subresponses can increase the size of the composite response unnecessarily and make the
composite response harder to parse.
You can simplify the composite response by suppressing the amount of information returned for one or more
subrequests. To do this, include the following with each relevant subrequest:
"includeResponse": false
For example:
{
"requests": [
{
"method": "post",
"body": {
"data": {
"attributes": {
}
}
},
},
...
The composite response still includes a subresponse for the subrequest. But instead of providing the endpoint's
default response, the subresponse appears as:
{
"responseIncluded": false
},
The responseIncluded field defaults to true. If you want a detailed response for a given subrequest, simply omit
the responseIncluded reference.
Using query parameters in subrequests

For a POST or PATCH subrequest, you can also refine which fields are returned. To do this, use the fields query
parameter. The syntax for this is:
{
"requests": [
{
"method": "<post/patch>",
"uri": "<path>",
"body": {
"data": {
"attributes": {
...
}
}
},
"parameters" : {
"fields" : "<value>"
}
},
...
]
}
For example, the following code snippet creates an activity. For the subresponse, it specifies to include only the
activity's ID and the assigned user.
{
"requests": [
{
"method": "post",
"body": {
"data": {
"attributes": {
}
}
},
"parameters" : {
"fields" : "id,assignedUser"
}
},
...
For a given API, you can see a complete list of all query parameters that can be used in composite requests by
executing a GET /openapi.json call. If a query parameter is available to composite requests, the OpenAPI output
will include the following line: "x-gw-allowForCompositeApi": true.
The selections section

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

}
],
"selections": [
{
"uri": "/common/v1/activities/${newActivityId}"
}
]
}
For the complete syntax that includes all composite request features, see “Complete composite request syntax” on
page 93.
Using query parameters in the selections section

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

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

{
"parameters" : {
"fields" : "assignedUser,dueDate,priority,subject",
"filter" : ["dueDate:gt:2022-12-20","status:in:open,complete"],
"includeTotal" : true,
"pageSize" : 5,
"sort" : ["dueDate"]
}
For a given API, you can see a complete list of all query parameters that can be used in composite requests by
executing a GET /openapi.json call. If a query parameter is available to composite requests, the OpenAPI output
will include the following line: "x-gw-allowForCompositeApi": true.
Composite requests that execute only queries
You can create a composite request that does not create or modify data and instead only queries for data. To do this,
create a composite request with only a selections section and no requests section. In this case, the GETs in the
selections section are always executed.
Responses to the selections subrequests
When a composite request contains a selections section, the response also contains a selections section. This
section has the same structure as the responses section. It contains one subresponse for each subselection. Every
subresponse has three sections:
• A body section, which by default contains the default response data defined in the corresponding endpoint.
• A headers section, which contains any custom headers.
• A status field, which indicates the subresponse's status code.
Composite request limitations

Composite requests have the following general limitations:
• The number of subrequests and subselections in a single composite request must be less than or equal to the value
of the MaximumAllowedNumberOfCompositeSubRequests configuration parameter. (In the base configuration,
this is set to 100.)
• The subrequests can make use of other endpoints that are part of Cloud API. However, they cannot make use of
endpoints outside of Cloud API, such as custom endpoints created by an insurer.
• You cannot use request inclusion in composite requests.
◦ For more information on request inclusion, see “Request inclusion” on page 95.
• You cannot include a subrequest that uses a content type other than application/json.
◦ For example, you cannot work with document resources in composite requests, as documents use multipart/
form-data.
• There is no mechanism for iterating over a set of things.
◦ For example, you cannot start with a list of elements and include related resources for each item in that list.
There 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 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": [
{
},
{
},
{
"requestError": {
"details": [
{
"message": "Schema definition 'ext.common.v1.common_ext-
1.0#/definitions/Note' does not define any property
named 'ueDate'",
"properties": {
"lineNumber": 1,
"parameterLocation": "body",
"parameterName": "body"
}
}
],
"developerMessage": "The request parameters or body had issues.
See the details elements for exact details of the problems.",
"errorCode": "gw.api.rest.exceptions.BadInputException",
"status": 400,
"userMessage": "The request parameters or body had issues"
},
"status": 400
},
{
"skipped": true
},
{
"skipped": true
}
],
"selections": [
{
"skipped": true
}
]
}
If there is an error in the selections section only, the subrequests in the requests section will execute, the data
will be committed, and the composite request will return with a 200 response code, indicating success. Cloud API
also attempts to execute each subselection as best as possible.
Logging
Cloud API logs information about composite requests at both the composite request level and the subrequest/
subselection level. This information appears in the logs under the CompositeSubRequest marker, which is a child of
the normal RestRequest marker.
Each subrequest and subselection log message details information for that subrequest/subselection, such as the
actual path, the HTTP method, and the apiFqn. The same log parameter names and conventions are used for both the
parent request logging and the subrequest logging, such as whether a given value is logged with an empty string or
whether it is omitted. However:
• Some parameters are always omitted at the subrequest level because they only make sense for the parent request.
• Some additional composite-specific parameters are added.
For example, suppose you executed the previouslly composite request example in which a composite request creates
two notes for activity xc:202. The corresponding log entries could appear as follows. Note that the first message is
for the parent request and the next two messages are for the two subrequests:
server-id-207 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13
14:40:30,803 INFO <RestService[ GW.PL ]> Operation started
{path="/composite/v1/composite", from="[0:0:0:0:0:0:0:1]", method="POST",
query="", startTime=1227026673066900, message="", eventType="START",
serverID="server-id-207"}
server-id-207 aapplegate 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13

14:40:30,894 INFO <CompositeSubRequest[ RestRequest ]> Operation status
{path="/common/v1/activities/xc:202/notes", query="", method="POST",
pathTemplate="/common/v1/activities/{activityId}/notes",
apiFqn="ext.common.v1.common_ext-1.0", status=201, error="", userMessage="",
devMessage="", elapsedTimeMs=53, message="Composite API subrequest
succeeded", eventType="STATUS", serverID="server-id-207"}
server-id-207 aapplegate 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13

14:40:30,899 INFO <CompositeSubRequest[ RestRequest ]> Operation status
{path="/common/v1/activities/xc:202/notes", query="", method="POST",
pathTemplate="/common/v1/activities/{activityId}/notes",
apiFqn="ext.common.v1.common_ext-1.0", status=201, error="", userMessage="",
devMessage="", elapsedTimeMs=4, message="Composite API subrequest
succeeded", eventType="STATUS", serverID="server-id-207"}
Each subrequest or subselection always generates a log statement, whether the subrequest succeeded, failed, or was
skipped due to prior failures. A separate log statement is also added specifically for the commit of the composite
request, whether the composite request commit succeeded, failed, or was skipped.
Configuring the maximum number of subrequests

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

The following is the complete syntax for a composite request:
{
"requests": [
{
"method": "<post/patch/delete>",
"uri": "<path>",
"body": {
"data": {
"attributes": {
...
}
}
},
"parameters" : {
"fields" : "<value>"
},
"vars": [
{
"name": "<name>",
"path": "<path-starting-with-$>"
},
<next variable>,
...
],
},
{
<next subrequest>
},
...
{
<final subrequest>
}
],
"selections": [
{
"uri": "<pathForFirstQuery>",
"parameters" : {
"fields" : "<value>",
"filter" : [<value>],
"includeTotal" : <value>,
"pageOffset" : <value>,
"pageSize" : <value>,
"sort" : [<value>]
}
},
{
<next subselection>
},
...
{
<final subselection>
}
]
}

chapter 10
Request inclusion
Request inclusion is a technique for POSTs and PATCHes in which the call consists of the following:
• A single parent request that creates or modifies a resource
• One or more child requests that create or modify resources related to the parent resource
If either the parent request or any child request fails, the entire request fails.
The parent resource is often referred to as the root resource. The root resource is specified in the payload's data
section. The related resources are specified in the payload's included section.
For example, a caller can use a single POST /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".
Syntax for simple parent/child relationships

In most cases, the relationship between the root resource and an included resource is a simple parent/child
relationship. Examples of this include:
• An activity and its notes
• An account and its AccountLocations
When using request inclusion for simple parent/child relationships, the JSON has the following structure:
{
"data" : {
"attributes": {
...
}
},
"included": {
"<resourceType>": [
{
"attributes": {
...
},
"method": "post",
"uri": "/../this/..."
Request inclusion 95
}
]
}
}
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, the system APIs 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 /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".
The uri must also specify the ID of the root resource. When the root resource and the included resources are being
created at the same time, the root resource does not yet have an ID. Therefore, the keyword this is used in the uri to
represent the root resource's ID.
Example of request inclusion for simple parent/child relationships

The following payload is an example of creating 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"
}
]
96 chapter 10: Request inclusion

}
}
Syntax for named relationships

In some cases, the relationship between the root resource and an included resource is more than just a parent/child
relationship. It is a "named relationship" in which the relationship has a special designation or label.
For example, every 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:
• 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".
The uri must specify the ID of the root resource. When the root resource and the included resources are being
created at the same time, the root resource does not yet have an ID. Therefore, the keyword this is used in the uri to
represent the root resource's ID.
Example of request inclusion for named relationships

The following payload is an example of creating an account and an AccountContact for the account whose
relationship is "accountHolder". (Accounts also require a primary location, so the payload also create an
AccountLocation whose relationship is "primaryLocation".) For more information on creating accounts, see
“Creating an account” on page 125.
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"
}
]
}
},
"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",

}
],
"AccountLocation": [
{
"attributes": {
"locationCode": "0001",
"locationName": "Location 0001",
"nonSpecific": true,
"state": {
"code": "CA"
}
},
"method": "post",
"refid": "newloc",
"uri": "/account/v1/accounts/this/locations"
}
]
}
}
Additional request inclusion behaviors

PATCHing and POSTing in a single request
When you execute a POST with request inclusion, the operation for each included resource must also be POST.
When you execute a PATCH with request inclusion, the operation for an included resource could be either POST or
PATCH.
• If you want to modify an existing resource and create a new related resource, the included resource's operation is
POST.
• If you want to modify an existing resource and modify an existing related resource, the included resource's
operation is PATCH.
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".
The system APIs 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.

chapter 11
Batch requests
From a system 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 response 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.
Batch requests are limited to a maximum number of subrequests. For more information, see “Configuring the
maximum number of subrequests” on page 105.
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":
{
"attributes": {
Batch requests 101

...
}
}
},
{
"method": "<method>",
"path": "<path>",
"query": "<queryParameters>",
"data":
{
"attributes": {
...
}
}
},
...
]
}
where:
• <method> is the operation 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/cc:22/activities/cc:55. The path within a batch is: /policies/cc:22/
activities/cc:55
• <queryParmaters> is an optional string of query parameters. Start this string without an initial "?".
• <field1/<value> are the field and value pairs of the request body.
The following sections provide examples of how to use this syntax.
Optional subrequest attributes

A subrequest can optionally have query parameters that refine the corresponding subresponse payload.
By default, each subrequest inherits the information in the headers of the main request object. The one exception to
this is the GW-Checksum header. This header is not inherited because it is unlikely that a single checksum value will
correspond to multiple sub-requests. You can optionally specify header values for an individual subrequest, which
will override the corresponding values in the main request header.
If a subrequest fails, the default is to continue processing the remaining subrequests. For each subrequest, you can
optionally specify that if the subrequest fails, 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": [
{
102 chapter 11: Batch requests

"method": "get",
"path": "/policies/demo_sample:1"
},
{
"method": "get",
},
{
"method": "get",
}
]
}
Batch requests with query parameters

The following is an example of a batch request with multiple GET subrequests. This example includes query
parameters for some of the GETs. As shown in the example, it is possible for some subrequests to use query
parameters while others do not. The subrequests that use query parameters can use different query parameters.
The response will consist of three subresponses. The fields in each subresponse will vary based on the query
parameters.
{
"requests": [
{
"method": "get",
"path": "/policies/demo_sample:1",
"query": "sort=createdDate"
},
{
"method": "get",
"path": "/policies/demo_sample:2",
"query": "fields=*all"
},
{
"method": "get",
}
]
}
Batch requests with request payloads

The following is an example of a batch request with multiple POST subrequests. This example includes request
payloads for each subrequest.
In this example, two notes are POSTed to different activities. But it would also be possible to POST each note to the
same activity.
{
"requests": [
{
"method": "post",
"path": "/activities/xc:11/notes",
"data":
{
"attributes": {
"body": "Batch note 1"
}
}
},
{
"method": "post",
"data":
{
"attributes": {
"body": "Batch note 2"
}
}
}
Batch requests 103

]
}
Batch requests with distinct operations

Every subrequest in a batch request is distinct from the other subrequests. There is no requirement for any
subrequest to share any attribute with any other subrequest. Thus, the following is an example of a batch request
with multiple subrequests where each subrequest uses a different operation.
{
"requests": [
{
"method": "post",
"path": "/activities/xc:21/notes"
"body": {
"data": {
"attributes": {
"body": "Batch activity 1",
"subject": "Batch activity 1",
"topic": {
"code": "general",
"name": "General"
}
}
}
}
},
{
"method": "patch",
"path": "/notes/xc:22",
"body": {
"data": {
"attributes": {
"body": "PATCHed note body"
}
}
},
},
{
"method": "delete",
"path": "/notes/xc:23"
},
{
"method": "get",
"query": "sort=subject&fields=id,subject"
}
]
}
Administering batch requests

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

The following is an example of a batch request where each subrequest has a header that overrides the main request
header.
{
"requests": [
{
"method": "delete",
"path": "/activities/xc:55",
"headers": [

{
"name": "GW-Checksum",
"value": "2"
}
]
},
{
"method": "delete",
"headers": [
{
"name": "GW-Checksum",
"value": "4"
}
]
}
]
}
Specifying onFail behavior

The following is an example of a batch request that uses onFail to specify that if any of the subrequests fail, the
remaining subrequests need to be skipped.
{
"requests": [
{
"method": "patch",
"body": {
"data": {
"attributes": {
"subject": "PATCH body 1"
}
}
},
"onFail": "abort"
},
{
"method": "patch",
"body": {
"data": {
"attributes": {
}
}
},
"onFail": "abort"
},
{
"method": "patch",
"body": {
"data": {
"attributes": {
}
}
}
}
]
}
Configuring the maximum number of subrequests

Batch requests are limited to a maximum number of subrequests. The maximum is specified by the
MaximumAllowedNumberOfBatchSubRequests configuration parameter. In the base configuration, this parameter is
set to 100. Batch requests with more than the maximum number of subrequests fail with a BadInputException.
The greater the number of subrequests in a batch request, the greater the chances that there will be a compromise in
performance. A batch request with the maximum number of subrequests could result in a slow response, depending
on what the maximum is and what those subrequests are doing.
Batch requests 105
In the base configuration, the maximum number of subrequests is 100. This can be raised to a greater value.
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.
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.

chapter 12
Lost updates and checksums
This topic defines lost updates and discusses how you can prevent them through the use of checksums.
• “Tutorial: PATCH an activity using checksums” on page 109
• “Tutorial: Assign an activity using checksums” on page 110
• “Tutorial: DELETE a note using checksums” on page 111
Lost updates
Business processes often span multiple system API calls. When this occurs, the first call is typically either a GET
that retrieves data or a POST that creates data. A later API call may attempt to modify the resource queried for or
created in the initial GET or POST.
Some other process could potentially 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 the system APIs, 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 107

Checksums
A checksum is a string value that identifies the "version" of a particular resource. The system APIs calculate
checksums as needed based on information about the underlying entities in the PolicyCenter database.
When a process modifies data, either through user action, system APIs, or other process, the system APIs calculate 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"
}
}
In many cases, checksums are simple integer values that are incremented with each update. However, this is not
always the case. For some resources, the checksum is a more complicated string value, such as "fwer:3245-11xwj".
Also, when a checksum is an integer, there is also 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 system API requests to only the checksums returned in previous
responses.
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 110.)
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 (2).
{
"data": {
"attributes": {
"priority": {
108 chapter 12: Lost updates and checksums

"code": "urgent"
}
},
"checksum": "2"
}
}
Checksums can be specified on the root resource and on any included resource. Specifying a checksum for any one
resource does not require you to specify checksums for the others. For example:
• You could specify a checksum for only the root resource.
• You could specify a checksum for only one of the included resources.
• You could specify a checksum for the root resource and some of the included resources, but not all of the
included resources.
Tutorial: PATCH an activity using checksums

In this tutorial, you will attempt to PATCH an activity twice. Both PATCHes will include a checksum value. The
first PATCH will succeed, and the second will fail.
Tutorial steps
%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>".)
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>
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

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
%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>".)
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.
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
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.
Result
The response appears below the request. Depending on the checksum value provided, the response will either
include a success code or an error message.
Tutorial: DELETE a note using checksums

In this tutorial, you will send calls as 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 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
%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 tab.
a. On the Authorization tab, select Basic Auth using user aclinton and password gw.
a. POST http://localhost:8180/pc/rest/common/v1/activities/<activityId>/notes
{
"data":
{
"attributes": {
"body": "API tutorial note to be deleted with a checksum"
}
}
}
7. Click Send. In the response payload, identify the note's id.

8. Open a third request tab and right-clicking the second tab and selecting Duplicate Tab tab.
a. Because it is a duplicate of the second tab, this tab also uses user 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. Add the checksum to the header
a. In the first row of tabs (the one that starts with Params), click Headers.
b. Scroll to the bottom of the existing key/value list.
c. In the blank row at the bottom of the key/value list, enter the following:
• KEY: GW-Checksum
• VALUE: 99
12. Click Send. The checksum value in the header does not match the checksum value for the note calculated by
PolicyCenter. So, the DELETE is unsuccessful and an error message appears.
13. Change the checksum value so that it matches the one from the POST payload.
14. Click Send a second time. Now, the checksum value in the header matches the checksum value for the note
calculated by PolicyCenter. So, the DELETE is successful. (The response to a successful DELETE is "204 -
No content".)

chapter 13
Cloud API headers
This topic describes 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. 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 the API allows the commit only if the
checksum in the header matches the checksum value
from PolicyCenter.
For more information, see “Checksums” on page 108.
GW-DBTransaction-ID String of up to 128 char- This can prevent duplicate requests.
acters When specified, this is used as the database transaction
ID for this request. The system 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 be globally unique across all clients,
APIs and web services.
For more information, see “Preventing duplicate data-
base transactions” on page 115.
Cloud API headers 113


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 re-
quests. The POST triggers "warm up" activities for the
endpoint, such as loading of Java and Gosu classes. But
the header prevents any data from being committed.
This request can improve the performance of subse-
quent requests to that endpoint.
For more information, see “Warming up an endpoint”
on page 116.
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 “Policy trans-
actions” on page 153.
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 used when processing the re-
quest.
For more information, see “Globalization” on page 119.
GW-Locale String This sets the locale used when processing the request.
For more information, see “Globalization” on page 119.
GW-UnknownPropertyHandling One of these string val- This specifies the behavior for handling request pay-
ues: loads with unknown properties. The default behavior is
• log reject.
• reject For more information, see “Handling a call with un-
• ignore known elements” on page 117.
GW-UnknownQueryParamHandling One of these string val- This specifies the behavior for handling URLs with un-
ues: known query parameters. The default behavior is
• log reject.
• reject For more information, see “Handling a call with un-
• ignore known elements” on page 117.
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 Authentication
Guide.
GW-ValidateResponseHandling Boolean 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 APIs.
For more information, see “Validating response pay-
loads against additional constraints” on page 117.
114 chapter 13: Cloud API headers


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 “Routing related API calls in
clustered environments” on page 33.
X-Correlation-ID String This permits a customer to trace a request from its ini-
tial 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 im-
plementation of TraceabilityIDPlugin plugin. The
default implementation uses this value, if specified, or a
generated UID. However, another implementation may
always generate a unique ID and log the relationship
between these incoming values and the generated UID.
This header can be repeated, but the resulting string
will just be the comma separated values.
(Note: This header predates the REST API Framework
and was created prior to the convention of using "GW-"
at the start of header names.)
Send a request with a Cloud API header using Postman

About this task
You can include Cloud API headers in calls executed from Postman.
Procedure
2. Specify authorization as appropriate.
3. Add the header and header value.
• In the first row of tabs (the one that starts with Params), click Headers.
• Scroll to the bottom of the existing key/value list.
• In the blank row at the bottom of the key/value list, enter the header name in KEY column and its value in
the VALUE column.
4. Enter the request operation and URL.
5. Click Send.
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 system API call, the system 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. The system 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. The system API assumes the transaction has already been
committed, and the call is rejected. The system API returns a 400 status code with an
gw.api.webservice.exception.AlreadyExecutedException error.
For the call to success, 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 system APIs that commit data to the database.
• It only works when the system API commits a single time only. (System APIs that commit multiple times are
rare.)
• It only works if the commit is either the only side effect of the call, or if the commit happens before any other
side effects, such as the sending of notifications to external systems.
Duplicate requests do not return identical responses. The first request will succeed, but subsequent requests will fail.
It is the responsibility of the caller application to decide how or if to handle this situation.
Warming up an endpoint
The first time a caller application makes a call to a Cloud API endpoint, the call may take longer to process than
normal. This is because the Guidewire server may need to execute tasks for the first call that it does not need to re-
execute for subsequent tasks, such as:
• Loading Java and Gosu classes
• Parsing and loading configuration files that are lazy-loaded on the first reference
• Loading data from the database or other sources into local caches
• Initializing database connections
A caller application may want to avoid having this slow processing time occur during a genuine business call.
Therefore, the caller application may want to "warm up" the endpoint. This involves sending a dummy "warm-up
request" to trigger these initial tasks. The warm-up request helps subsequent requests execute more rapidly.
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 dummy data
downstream.

Handling a call with unknown elements

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

Serialization of the HTTP response is one of the final steps in handling a request. Both the response body and
response headers need to be serialized, with the response body written to the HttpServletResponse output stream
and the response headers turned into Strings that the servlet container is responsible for writing to the response. The
system APIs support 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 API 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 the system API validate its responses against the
declared schema. To do this, include the header and set its value to true.


chapter 14
Globalization
In the context of Guidewire InsuranceSuite applications, globalization refers to the internationalization and
localization aspects of system configuration. The system APIs can work with the globalization settings of your
system. For details on how Guidewire InsuranceSuite applications support globalization, refer to the Globalization
Guide.
Specifying language and locale in API requests

By default, system API calls return data in the format of the default language and locale of your PolicyCenter
instance, as specified by the DefaultApplicationLanguage and DefaultApplicationLocale system parameters
in config.xml. If your instance supports additional languages and locales, then you can construct API calls to
request data in those alternative formats.
Callers can specify a preferred language and locale in the request header. Guidewire provides two header fields for
this purpose, GW-Language and GW-Locale. The GW-Language field accepts an ISO 639-1 code designating the
language, while the GW-Locale field takes the ISO 639-1 language code along with the ISO 3166-1 alpha-2 locale
code, separated by an underscore.
For example, the ISO 639-1 language code for Japanese is ja, and the ISO 3166-1 alpha-2 locale code for Japan is
JP. The following code block displays a request header with the GW-Language and GW-Locale fields set to Japanese
language and locale, respectively:
GET /pc/rest/account/v1/accounts/pc:102? HTTP/1.1
Host: localhost:8180
GW-Language: ja
GW-Locale: ja_JP
Authorization: Basic c3U6Z3c=
Addresses and locales

The formatting of postal addresses can vary by country. PolicyCenter provides a flexible way to format addresses
using the Address entity along with the State and Country typelists. In the system APIs, this address data is mapped
to the Address schema found in the Common API.
The following table lists each Address property with its associated Guidewire Address entity field:
Address property GW entity mapping Description

addressLine1 Address.AddressLine1 First line of a street address
Globalization 119
Address property GW entity mapping Description

addressLine1Kanji Address.AddressLine1Kanji First line of a street address (in Japanese)
addressLine2 Address.AddressLine2 Second line of a street address

addressLine2Kanji Address.AddressLine2Kanji Second line of a street address (in Japanese)
addressLine3 Address.AddressLine3 Third line of a street address

area Address.State Country-specific administrative area, as defined in the State typelist
city Address.City City or locality
cityKanji Address.CityKanji City or locality (in Japanese)
country Address.Country Country code, as defined in the Country typelist
county Address.State Country-specific administrative area, as defined in the State typelist
department Address.State Country-specific administrative area, as defined in the State typelist
district Address.State Country-specific administrative area, as defined in the State typelist
do_si Address.State Country-specific administrative area, as defined in the State typelist
emirate Address.State Country-specific administrative area, as defined in the State typelist
island Address.State Country-specific administrative area, as defined in the State typelist
oblast Address.State Country-specific administrative area, as defined in the State typelist
parish Address.State Country-specific administrative area, as defined in the State typelist
postalCode Address.PostalCode Postal or zip code
prefecture Address.State Country-specific administrative area, as defined in the State typelist
province Address.State Country-specific administrative area, as defined in the State typelist
sortingCode Address.CEDEXBureau Sorting code (France only)
state Address.State Country-specific administrative area, as defined in the State typelist
Address locale configuration

While the Address schema supports a wide range of properties for locale-specific administrative areas, only one
such property can be used in a given address. For example, an address cannot use both state and province
properties. Furthermore, only one administrative area property is valid in an address, and this is determined by the
country or territory of the address. Studio provides an address configuration file at configuration/config/
Integration/i18n/addresses.i18n.yaml:
countries:
. . .
JP:
name: Japan
addressFields: addressLine1, addressLine1Kanji, addressLine2, addressLine2Kanji, addressLine3, city, cityKanji,
prefecture, postalCode
addressRequire: addressLine1, city, prefecture, postalCode
. . .
US:
name: United States
addressFields: addressLine1, addressLine2, addressLine3, city, county, state, postalCode
addressRequire: addressLine1, city, state, postalCode
. . .
120 chapter 14: Globalization

The countries field contains a property for each country or region, the name of which is derived from the relevant
ISO 3166-1 alpha-2 country code. The previous code block displays two such properties, JP and US, for Japan and
the United States, respectively. Each country property contains the following fields and values:
• name: The name of the region (typically country or territory)
• addressFields: The address fields from the Address schema that can be included in an address for the country
or region
• addressRequire: The minimum subset of address fields that must be included in an address for the country or
region
When starting the server, the addresses.i18n.yaml file is loaded, and its rules are applied to Address resources.
The Address schema contains code that enables this functionality:
"Address": {
"type": "object",
"x-gw-extensions": {
"discriminatorProperty": "country"
},
"properties": {
. . .
}
}
}
In the previous code snippet, the x-gw-extensions.discriminatorProperty field is set to country. As a result,
when setting the country property on an Address resource, the address fields associated with that country will be
valid for that resource, and the fields not associated with the country will be unavailable.
Globalization 121
122 chapter 14: Globalization

Part 2
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
chapter 15
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 133.
Creating an account
To create a new account through Cloud API, use the following endpoint:
• POST /account/v1/accounts
Minimum creation criteria

To create an account, the minimum amount of information you must provide is:
• The 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 129.
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 results of each approach are the same.
Creating accounts 125

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 (firstName?)
◦ 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": {
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"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": {
"primaryAddress": {
"state": {
"code": "CA"
}
}
},
"method": "post",
"refid": "BillPreston",
}
]
126 chapter 15: Creating accounts

}
}
The primary location

The primary location is a location, identified as address or some portion of an address, that is the primary location
associated with the account. This information is stored in PolicyCenter as an AccountLocation.
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 contact 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 results of each approach are the same.
In either approach, you must by default 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": {
"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": {
"refid": "newlocation"
},
...
},
"included": {
"AccountLocation": [
{
"attributes": {
"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 "specific" the
location is. This flag defaults to false.
• 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 required for a complete address is a street address, city, state or
province, and postal code.
◦ This is the flag's default value. If the nonSpecific flag is not specified, then it is considered specific and must
be 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 false.
For example, the following snippet specifies the primary location using the initialPrimaryLocation attribute and
a non-specific address:
{
"data": {
"attributes": {
"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 319.
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": {
"primaryAddress": {
"state": {
"code": "CA"
}
}
},
"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, if the account appears to be a
duplicate of an existing account, PolicyCenter alerts the user through the user interface with the names of any
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.
Configuring name clearance

Name clearance logic can be configured. If it is configured, then if you attempt to create a duplicate account through
the POST /accounts endpoint, the call may succeed or fail based on the newly configured logic.
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 also have several types of child objects. They are summarized in the following table.
Object type More information

Additional account contacts “Account contacts” on page 137
Additional account locations “Account locations” on page 138
Activities “Activities” on page 281
Documents “Documents” on page 289
Notes “Notes” on page 295
Jobs “Account jobs and policies” on page 139
Policies “Account jobs and policies” on page 139
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 respond 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. If the quote is agreeable, they can 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 Authentication Guide.


chapter 16
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 125.
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",
"code": "individual",
"name": "Individual"
},
"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 133

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"
}
}
}
Searching by producer
Two search criteria pertain to producers: producerCode and organization.
134 chapter 16: Managing accounts
If you know a producer's code, you can search for all accounts associated with that producer by including the
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:
mPlease 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 claim searches, which 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's name (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"
}
}
}

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:
• 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}
Creating account contacts

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

At a minimum, 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
For example, the following request creates a new contact for account pc:202.
POST /account/v1/accounts/pc:202/contacts

"data": {
"attributes": {
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"state": {
"code": "CA"
}
}
}
}
}
Modifying account contacts

Use the following endpoints to modify or delete an account contact:
• PATCH /accounts/{accountId}/contacts/{contactId}
• DELETE /accounts/{accountId}/contacts/{contactId}
For example, the following request assigns an email for account contact pc:444 on account pc:202.
PATCH /account/v1/accounts/pc:202/contacts/pc:444
{
"data": {
"attributes": {
"emailAddress1": "sstewart@email.com"
}
}
}
The following request deletes account contact pc:444 on account pc:202.

DELETE /account/v1/accounts/pc:202/contacts/pc:444
<no request body>
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 /accounts/{accountId}/locations
• GET /accounts/{accountId}/locations/{locationId}
Creating account locations

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


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": {
"state": {
"code": "CA"
}
}
}
}
Modifying account locations

Use the following endpoints to modify an account location:
• PATCH /accounts/{accountId}/locations/{locationId}
For example, the following request assigns a location name for account location pc:717 on account pc:202.
POST /account/v1/accounts/pc:202/contacts/pc:717
{
"data": {
"attributes": {
"locationName": "Employee parking lot"
}
}
}
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 /accounts/{accountId}/jobs
• GET /accounts/{accountId}/policies
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 /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.

chapter 17
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",
},
"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": {
Managing bound policies 141

"amount": "764.00",
"currency": "usd"
}
}
...
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 must omit companyName.
◦ The search returns only policies where the insured is an exact match of the named person.
• When searching by official ID:
◦ 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":
142 chapter 17: Managing bound policies
{
"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"
}
}
}
}
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 claim 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.
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 /accounts/{accountId}/move-policies
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
Most policies have only one producer associated with them, and that producer remains with the policy for the entire
term. 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 Policy resource stores producer information in the following fields:
• organization - The organization representing the producer
• producerCode - The producer code that associates the producer with the policy
Changing a policy's producer

Sometimes, 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.
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.
PolicyCenter supports the ability to associate multiple producers with a policy and to designate a producer as either
the producer of record or the producer of service. For more information on the business functionality of producers or
record and producers of service, see the Application Guide.
When the producer on a policy changes mid-term, the Policy resource stores producer information in the following
fields:
• organization - The organization representing the producer of record
• organizationOfService - The organization representing the producer of service
• producerCode - The producer code that associates the producer with the policy of record
• producerCodeOfService - The producer code that associates the producer with the policy of service
(If the producer has not changed, the organizationOfService value is identical to the organization value, and
the producerCodeOfService value is identical to the producerCode value.)
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 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}
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:
...
"primaryInsured": {
"id": "test_pp:2",
"type": "PolicyContact",
"uri": "/job/v1/jobs/pc:SthuffsigqVMeo_Y1FwND/contacts/test_pp:2"
},
...
Querying for additional named insured

Use the following endpoint to retrieve a policy's additional named insured, if any:
• 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 the role and a policy contact. The element specifies the account contact who has this
Additional Named Insured role on the policy, and optionally the nature of the relationship between the Additional
Named Insured and the primary insured.
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.
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 change” on page 169.
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.
...
"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 change” on page 169.
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.
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-
questions qualification), and their answers, if any
GET /policies/{policyId}/ The set of location-level questions for the specified location from the job (which are
locations/{locationId}/ typically 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 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.
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.
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"
}
},
...
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"
}
},
...
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 249.
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 275.

Part 3
Business flows: Job types
The following topics discuss how caller applications can manage specific types of jobs (also known as policy
transactions) within PolicyCenter. This includes:
• Submissions
• Renewals
• Policy changes
• Cancellations
• Reinstatements
• Rewrites (including rewrite new account jobs)
chapter 18
Policy transactions
The system APIs support the following policy transactions:

• Submission
• Issuance
• Renewal
• Cancellation
• Policy change
• Reinstatement
• Rewrite
• Rewrite new account
Transactions not in this list are not supported at this time.
When using the system APIs, policy transactions are conducted through the Policy and Job APIs. The Policy API
provides endpoints for initiating policy transactions on existing policies. The Job API provides endpoints for
modifying, quoting, and completing policy transactions, as well as for creating new policies (submissions). The
LOB-specific aspects of policy transactions are encapsulated in the Job API.
Note: The base configuration of the system APIs does not include LOB-specific APIs. Clients must
generate LOB-specific APIs using Advanced Product Designer (APD). Once generated, the LOB-
specific API endpoints are available through the Job API. For details, see “Generate LOB-specific
APIs” on page 367.
Conceptually, a policy transaction entails four basic steps:
1. Initiate the policy transaction through a business action POST.
• This step creates a new job element, on which subsequent actions will be applied.
• The new job is in Draft state, and thus can be modified.
2. Modify the job as needed.
• Depending on the policy transaction type, a number of calls might be required to apply all necessary data to
the job.
3. Quote the job.
• This step changes the job from Draft to Quoted state.
• Jobs in Quoted state cannot be modified. To further modify a quoted job, it must be changed to Draft state,
in which case the process then reverts to step 2.
4. Complete the policy transaction by finalizing the job.
• A quoted job can be accepted (bound) or declined.
Policy transactions 153
Initiating the policy transaction

To initiate a policy transaction, a caller submits a business action POST to an appropriate endpoint. The following
table lists the policy transaction type with its relevant endpoint:
Policy transaction Endpoint

Submission /job/v1/submissions
Issuance /policy/v1/policies/{policyId}/issue
Renewal /policy/v1/policies/{policyId}/renew
Cancellation /policy/v1/policies/{policyId}/cancel
Policy change /policy/v1/policies/{policyId}/change
Reinstatement /policy/v1/policies/{policyId}/reinstate
Rewrite /policy/v1/policies/{policyId}/rewrite
Rewrite new account /policy/v1/policies/{policyId}/rewrite-account
All policy transactions other than submissions are initiated from an existing policy element through a Policy API
call. The submission policy transaction is initiated using the Job API. In either case, the call returns a response
payload that contains a JSON object for a new job element that is accessible through the Job API. Subsequent
actions for the policy transaction are executed on this job element.
The following example depicts portions of a response payload returned by a call to initiate a submission policy
transaction for a personal auto line:
{
"data": {
"attributes": {
"account": {
"displayName": "0015863842",
"id": "pc:401",
"type": "Account",
"uri": "/account/v1/accounts/pc:401"
},
. . .
"id": "pc:601",
. . .
"jobStatus": {
"code": "Draft",
"name": "Draft"
},
"jobType": {
"code": "Submission",
"name": "Submission"
},
. . .
"product": {
"displayName": "Personal Auto",
},
. . .
},
. . .
}
154 chapter 18: Policy transactions

}
}
• The id property contains the ID of the new job element, in this case pc:601.
• The account.id property is the ID for the account holder. It is important to not mistake account.id for id.
• The jobStatus property indicates that the job is in Draft state.
• The jobType property shows that the job is for a submission policy transaction.
Subsequent actions for this policy transaction are executed on the /job/v1/jobs/pc:601 element.
Modifying the job

As stated previously, initiating a policy transaction produces a job element that is accessible through the Job API
(/job/v1/jobs/{jobId}). All subsequent work involved in processing a policy transaction occurs on this job
element.
Depending on the policy transaction type, it might be necessary to modify the job by submitting additional data. For
example, after initiating a submission policy transaction for a personal auto line, a caller must modify the job by
adding vehicles and drivers and applying coverages.
Quoting the job

For any policy transaction, the associated job must be quoted before it can be completed. To generate a quote, a
caller submits a business action POST to /job/v1/jobs/{jobId}/quote. This action changes the job to Quoted
state. If subsequent modifications are deemed necessary, then the job must be reverted to Draft state by submitting a
business action POST to /job/v1/jobs/{jobId}/make-draft. After modifications are applied, the job must be
quoted again.
Completing the policy transaction

To complete the policy transaction, the job must be accepted (bound) or rejected.
For accepted policy transactions, in most cases the transaction can be completed by submitting a business action
POST to the /job/v1/jobs/{jobId}/bind-and-issue endpoint. This action binds the transaction to the policy.
A policy transaction can be rejected for a number of reasons. If the insurer rejects the transaction, then the job can be
rescinded through a business action POST to the /job/v1/jobs/{jobId}/decline. If the policy transaction
contains faulty data, then it can be discarded through a business action POST to the /job/v1/jobs/{jobId}/
withdrawn endpoint.
Transaction Condition Job status Endpoint

outcome
Accepted The account holder and insurer agree to the quote. Bound /job/v1/jobs/{jobId}/bind-and-
The policy is bound and issued. issue
Rejected The insurer declines to offer a policy to the account Declined /job/v1/jobs/{jobId}/decline
holder.
Rejected The quote contains erroneous data. Withdrawn /job/v1/jobs/{jobId}/withdrawn
Furthermore, some policy transaction types can be completed by being placed in Pending status.
The specific actions available to complete a policy transaction depend on the transaction type. For details, see
subsequent sections for each policy transaction type.
LOB-specific endpoints
Generally speaking, an LOB defines an insurance policy, which provides coverages (risk protection) for coverables
(risk exposures, such as tangible assets). Additionally, an LOB could define other policy features such as modifiers,
exclusions, or pre-qualification questions for underwriting.
After generating LOB-specific APIs using Advanced Product Designer (APD), the LOB-related endpoints are
contained in the Job API. In processing a policy transaction, a caller will add, revise, or remove data related to the
LOB.
The following sections provide general guidance on the data structures that can appear in LOB endpoints.
Products
Every job has at least one product. The available products can be accessed through the /job/v1/jobs/{jobId}/
lines collection. Each product can be found at /job/v1/jobs/{jobId}/lines/{productId}. Here, productId is
a placeholder for a specific product.
For example, on a job for a personal auto line policy, the personal auto line product is accessed through
the /job/v1/jobs/{jobId}/lines/PersonalAutoLine endpoint.
Coverables
Coverables refer to any risk exposures that can be covered by the LOB or product. Coverables are accessible as
collections on LOB endpoints. For example, one of the coverables for the PersonalAutoLine LOB is vehicle. Each
PersonalAutoLine typically has a collection of one or more vehicles. Coverables can also be nested under other
coverables. For example, another one of the coverables for PersonalAutoLine is driver. For each vehicle on a
PersonalAutoLine, there can be a collection of drivers for that vehicle.
The basic pattern for accessing coverables is as follows:
• /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}
• /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}/{coverableType}/
{coverableId}
Here, coverableType is a placeholder for a collection of some type of coverable, and coverableId refers to a
specific coverable.
For example, in a personal auto line, vehicles and drivers are coverables. In the Jobs API, vehicles can be accessed
through the /job/v1/jobs/{jobId}/lines/PersonalAutoLine/vehicles collection. Drivers associated with a
covered vehicle are can be accessed through the /job/v1/jobs/{jobId}/lines/PersonalAutoLine/vehicles/
{vehicleId}/drivers collection.
Also, the Job API provides a locations coverable type that is associated with the job directly, rather than the LOB.
This collection can be used to define coverables in certain LOBs, such as for commercial property.
Coverages
A coverage is protection from a specific risk. Coverages are attached to coverables. There are two basic types of
coverages: property and liability. A property coverage is a coverage for a tangible asset belonging to the insured,
such as a vehicle. A liability coverage protects the insured, such as covering a driver for damage done to another
vehicle.
The available coverages for a product can be accessed through the /job/v1/jobs/{jobId}/lines/{productId}/
coverages collection. Each coverage can be found at /job/v1/jobs/{jobId}/lines/{productId}/coverages/
{coverageId}. Depending on the LOB, coverages could be nested. For example, a location (a coverable) could
have a collection of buildings (child coverables), and a coverage would be applied to each building. For property
coverages, the basic pattern is /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}/
coverages. For liability coverages, the policy line itself is a coverable, and represents the named insureds. The
pattern is /job/v1/jobs/{jobId}/lines/{productId}/coverages.
For example, the personal auto line has both property (vehicle) and liability (driver) coverages. The vehicle
coverages can be accessed through the /job/v1/jobs/{jobId}/lines/PersonalAutoLine/vehicles/
{vehicleId}/coverages endpoint. The driver coverages cover liability, and thus can be found on the line
itself: /job/v1/jobs/{jobId}/line/PersonalAutoLine/coverages.
Modifiers
Modifiers are factors that are applied as part of a rating algorithm. For example, the personal auto line could have an
"Anti-Lock Breaks Discount" modifier for vehicles that provides a discount on the premium if the vehicle has anti-
lock breaks. Modifiers can be associated with coverables or with the LOB itself.
• /job/v1/jobs/{jobId}/lines/{productId}/modifiers
• /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}/modifiers
For example, the personal auto line could have an "Anti-Lock Breaks Discount" modifier for vehicles that provides
a discount on the premium if the vehicle has anti-lock breaks.
Exposures, exclusions, or conditions

An LOB might provide additional exposures, exclusions, or conditions. Exposures can refer to liability coverables,
such as a driver in an auto policy. Exclusions define causes of loss that are explicitly not covered by the policy, so
that the insurer has no exposure to claims in those areas. Conditions define contractual obligations of the insurance
policy that are neither a coverage nor an exclusion.
Exposures, exclusions, or conditions can be accessed at the LOB level.
For example, a workers compensation line could make workplace exclusions accessible through a /job/v1/jobs/
{jobId}/lines/WorkersCompLine/excluded-workplaces endpoint. Depending on the LOB, exclusions could be
defined on a coverable, in which case the pattern would be /job/v1/jobs/{jobId}/lines/{productId}/
{coverableType}/{coverableId}/{excludedType}/{excludedId}.
Pre-qualification questions for underwriting

In PolicyCenter, prequalifiction is accomplished through a series of questions answered during the submission
process that can reveal possible underwriting issues. Answers to pre-qualification questions can be used to raise
underwriting issues or block binding of the submission.
Pre-qualification could involve posing queries that are general to all products as well as specific to product, location,
or coverable. As such, depending on the LOB, pre-qualification questions could be accessed through the following
endpoints:
• /job/v1/jobs/{jobId}/questions
• /job/v1/jobs/{jobId}/locations/{locationId}/questions
• /job/v1/jobs/{jobId}/lines/{productId}/questions
• /job/v1/jobs/{jobId}/lines/{productId}/locations/{locationId}/questions
• /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}/questions
To illustrate, in a personal auto line, a GET request to /job/v1/jobs/{jobId}/questions could return the
following:
{
"data": {
"attributes": {
"answers": {
"q1": {
"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": {
"question": {
"displayName": "Has your license ever been canceled, suspended or revoked?",
"id": "q3"
},
"questionType": {
"code": "Choice",
"name": "Choice"
}
},
"q4": {
"question": {
"displayName": "Are you currently insured?",
"id": "q4"
},
"questionType": {
"code": "Boolean",
"name": "Boolean"
}
}
}
},
"checksum": "*",
"links": "*"
}
}

chapter 19
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 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 159
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 125.
Use the following endpoint to create a submission:
• POST /job/v1/submissions
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
◦ This must be specified as a string in the form YYYY-MM-DD.
• 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": {
}
}
}
}
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.
160 chapter 19: Submissions
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 185.
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 83.
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 base configuration Personal Auto product” on page 375.
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 261.
Completing the submission

A submission can be completed in one of several ways.
Submissions 161
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 action of both parties agreeing to the policy and making it a legally binding contract.
• Issuing refers to 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 and issues job pc:4040.
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 only bound. From a technical standpoint,
issuance is a policy transaction.
• 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:
For example, the following request quotes job pc:8808:
<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.
For example, the following request binds and issues issuance job pc:8808.
<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
For example, the following request withdraws job pc:4040.
Submissions 163
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:
• POST /job/v1/jobs/{jobId}/withdraw
For example, the following request withdraws job pc:4040.
<no request body>
The submission's status is changed to "Withdrawn".
Declining 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.
{
"data": {
"attributes": {
"rejectReason": {
"code": "PaymentHistory"
}
}
}
}
The submission's status is changed to "Declined".
Not taking a submission

• 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, pre-
qualification status and underwriter approval does 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 261.
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>
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.
Submissions 165
Feature Description More information

Contingencies An object that identifies an issue affecting a job or policy that must “Contingencies” on page 249
be resolved by a particular date.
Job locks A lock that indicates that there are associated underwriting issues “Job locks” on page 273
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 “Policy and job search” on
page 253
Multi-version The ability to create and compare multiple quotes for a single job “Multi-version quoting” on
quoting page 261
Out-of-sequence A conflict that occurs conflict occurs when a job has a transaction “Out-of-sequence conflicts” on
conflicts date later than another policy transaction, but an effective date page 255
earlier than that other policy transaction.
Rating overrides The ability to override a specific Cost for a specific quote “Rating overrides” on page 263
Underwriting issues An object attached to a job or policy that tracks an issue that may “Underwriting issues” on
require underwriter review page 267

chapter 20
Renewal
The renewal process extends the policy for another term beyond the current expiration date. It creates a new policy
period for an existing policy. The renewal policy transaction can be applied to a bound policy. For a general
overview of how to conduct policy transactions using the system APIs, see “Policy transactions” on page 153. For
details on the business functionality of renewals and other policy transactions in PolicyCenter, see Application
Guide.
Renew the policy

1. Initiate a renewal policy transaction.
Submit a POST request to the /policy/v1/policies/{policyId}/renew endpoint, containing an empty
request payload.
{
"data": {
"attributes": {}
}
}
The response payload contains the associated job. Use the job ID in subsequent calls.
2. Modify the job (optional).
The job is in Draft state, and can be modified. For example, the renewed policy could include a new
coverable. Details of modifying a job depend on the LOB and product.
For more information on how to modify a policy within the context of a job, see “Overview of modifying
3. Generate a quote.
Submit a business action POST to the /job/v1/jobs/{jobId}/quote endpoint.
4. Complete the policy transaction.
The following table illustrates the various ways that a quoted renewal job can be completed:
Transaction Condition Endpoint

outcome
Accepted renewal Issues the renewal immediately /job/v1/jobs/{jobId}/bind-and-
issue
Pending renewal Puts policy period in renewing status and starts the /job/v1/jobs/{jobId}/pending-
PendingRenwalWF workflow renew
Renewal 167
Transaction Condition Endpoint

outcome
Pending non-renewal Puts policy period in nonrenewing status and starts the /job/v1/jobs/{jobId}/pending-
PendingNonRenwalWF workflow non-renew
Pending not taken Puts policy period in nottaking status and starts the /job/v1/jobs/{jobId}/pending-
PendingNotTakenWF workflow not-take
Withdrawn Withdraws the job /job/v1/jobs/{jobId}/withdrawn
Submit a business action POST to the relevant endpoint.
168 chapter 20: Renewal

chapter 21
Policy change
A policy change modifies a policy in between the effective and expiration dates. This transaction type can be used to
apply changes to a policy, except for those that involve revising its effective date or the producer of record. For a
general overview of how to conduct policy transactions using the system APIs, see “Policy transactions” on
page 153. For details on the business functionality of policy changes and other policy transactions in PolicyCenter,
see Application Guide.
Change the policy

1. Initiate a policy change transaction.
Submit a business action POST to the /policy/v1/policies/{policyId}/change endpoint. The request
payload must include the job effective date.
{
"data": {
"attributes": {
"jobEffectiveDate": "2020-08-18"
}
}
}
The response payload contains the associated job, which is in Draft state. Use the job ID in subsequent calls.
2. Modify the job as necessary.
Modifying actions will depend on the LOB and product. For example, in the case of a personal auto line, a
caller could add a driver or revise driving percentages of a vehicle.
For more information on how to modify a policy within the context of a job, see “Overview of modifying
3. Sync coverages and modifiers.
To apply coverages, submit a business action POST to the /job/v1/jobs/{jobId}/lines/{lineId}/sync-
coverages endpoint. To apply modifiers, submit a business action POST to the /job/v1/jobs/{jobId}/
lines/{lineId}/sync-modifiers endpoint.
5. Complete the policy change transaction.
The following table illustrates the two ways that a quoted policy change job can be completed:
Policy change 169


outcome
Accepted The account holder and insurer agree to the quote, Bound /job/v1/jobs/{jobId}/bind-
and all necessary paperwork has been received by the and-issue
insurer. The policy is bound and issued.
Withdrawn The quote contains erroneous data. Withdrawn /job/v1/jobs/{jobId}/
withdrawn
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 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 /jobs/{jobId}/preemptions
The /preemptions endpoint returns two main types of information:
• An array of job diffs
• Information about the preempting job
170 chapter 21: Policy change
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": {
"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 of pc:421
◦ Effective date: 11/05/2021
Policy change 171
◦ Material changes: Adds a Honda Civic and associated coverages for driver Alicia Shirley
• Second policy change:
◦ Job number: 0004408964
◦ 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
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"
},
{
"entity": {
"displayName": "2000 Honda Civic in California",
"id": "32"
},
"field": "2000 Honda Civic in California"
},
{
"entity": {
"displayName": "Collision",
"id": "64"
},
"field": "Collision"
},
{
"entity": {
"displayName": "Comprehensive",
"id": "63"
},
"field": "Comprehensive"
},
{
"entity": {
"displayName": "Alicia Shirley",
"id": "15"

},
"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.
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
◦ Material changes: Adds a Honda Civic and associated coverages for driver Alicia Shirley
• Second policy change:
◦ Job number: 0004408964
◦ 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>
Policy change 173

RESPONSE:
{
"data": {
"attributes": {
"job": {
"id": "pc:505",
"isPreempted": false,
"jobNumber": "0004408964",
"jobStatus": {
"code": "Draft",
"name": "Draft"
},
"jobType": {
}
}
}
}
}
Next, you must quote the job.

<no request body>
RESPONSE:
{
"data": {
"attributes": {
"id": "pc:505",
"jobNumber": "0004408964",
"jobStatus": {
"code": "Quoted",
"name": "Quoted"
},
"jobType": {
},
"taxesAndSurcharges": {
"amount": "94.00",
"currency": "usd"
},
"totalCost": {
"amount": "1396.00",
"currency": "usd"
},
"totalPremium": {
"amount": "1302.00",
"currency": "usd"
}
}
}
}
And finally, you can bind and issue the job.

<no request body>
RESPONSE:
{
"data": {
"attributes": {
"id": "pc:505",
"jobNumber": "0004408964",
"jobStatus": {
"code": "Bound",
"name": "Bound"
},
"jobType": {

}
}
}
}
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 and that 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.
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 change 175


chapter 22
Cancellation
The cancellation policy transaction can be applied to a bound policy that is in force. A cancellation request must
include the requesting source (insurer or insured), a reason for the cancellation, and an effective date. The effective
date of the cancellation will depend on several factors, related to the requesting source and product configuration.
For a general overview of how to conduct policy transactions using the system APIs, see “Policy transactions” on
page 153. For details on cancellations and other policy transactions in PolicyCenter, see Application Guide.
Cancel the policy

1. Initiate the cancellation policy transaction.
Submit a business action POST to the /policy/v1/policies/{policyId}/cancel endpoint.
The request payload must contain at minimum the following fields and value types:
• cancellationReasonCode.code: A typecode from the ReasonCode typelist
• cancellationSource.code: A typecode from the CancellationSource typelist
• jobEffectiveDate: A date string
{
"data": {
"attributes": {
"cancellationReasonCode": {
"code": "cancel"
},
"cancellationSource": {
"code": "carrier"
},
}
}
}
The response payload contains the associated job, which is in Quoted state. Use the job ID in the subsequent
call.
2. Complete the cancellation.
The following table illustrates the various ways that a quoted cancellation job can be completed:
Transaction outcome Action Endpoint

Accepted Cancel the policy immediately /job/v1/jobs/{jobId}/bind-and-issue
Pending Schedule a cancellation for a future date /job/v1/jobs/{jobId}/pending-cancel
Cancellation 177
Transaction outcome Action Endpoint

Rescheduled Change the process date for the scheduled /job/v1/jobs/{jobId}/reschedule
cancellation
Rescinded Rescind the scheduled cancellation /job/v1/jobs/{jobId}/rescind
Withdrawn Withdraw the cancellation job /job/v1/jobs/{jobId}/withdrawn
178 chapter 22: Cancellation

chapter 23
Reinstatement
The reinstatement policy transaction can only be applied to a canceled policy. A reinstatement is executed when the
issue causing the cancellaton is rectified. For example, a reinstatement could occur when an insurer receives past-
due payment on a policy but had been canceled for lack of payment. For a general overview of how to conduct
policy transactions using the system APIs, see “Policy transactions” on page 153. For details on reinstatements and
other policy transactions in PolicyCenter, see Application Guide.
Reinstate the policy

1. Initiate a reinstatement policy transaction.
Submit a business action POST to the /policy/v1/policies/{policyId}/reinstate endpoint. The request
payload must include the reinstateCode.code property, which takes a typecode from the ReinstateCode
typelist.
{
"data": {
"attributes": {
"reinstateCode": {
"code": "payment"
}
}
}
}
The response payload contains the associated job, which is in Draft state. Use the job ID in the subsequent
call.
Submit a business action POST to the /job/v1/jobs/{jobId}/quote endpoint. Reinstatement (job effective)
date is automatically set to the cancellation date. Everything else in the original policy remains unchanged.
3. Complete the reinstatement policy transaction.
The following table illustrates the two ways that a quoted reinstatement job can be completed:

outcome
Accepted The account holder and insurer agree to the quote, Bound /job/v1/jobs/{jobId}/bind-
and all necessary paperwork has been received by the and-issue
insurer. The policy is bound and issued.
Reinstatement 179

outcome
Withdrawn The quote contains erroneous data. Withdrawn /job/v1/jobs/{jobId}/
withdrawn
180 chapter 23: Reinstatement

chapter 24
Rewrite and Rewrite New Account
The rewrite and rewrite new account policy transactions can be applied by an underwriter to a bound policy that is in
force. The rewrite policy transaction can be used to change the effective date of a policy or the producer of record.
The rewrite new account policy transaction can be used to clone an existing policy and assign it to a new account.
These actions cannot be executed in a policy change transaction. For a general overview of how to conduct policy
transactions using the system APIs, see “Policy transactions” on page 153. For details on rewrites and other policy
transactions in PolicyCenter, see 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
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": {
Rewrite and Rewrite New Account 181

"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 185.)
Submit a business action POST to the /job/v1/jobs/{jobId}/bind-and-issue endpoint.
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.
Submit a business action POST to the /job/v1/jobs/{jobId}/bind-and-issue endpoint.
182 chapter 24: Rewrite and Rewrite New Account

Part 4
Business flows: Job policies
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
chapter
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 Personal Auto Line LOB-specific “Lines” on page 189
that is used to define a
type of product offered
by an insurer
Coverable A thing that is covered Vehicle LOB-specific “Coverables and
by the policy coverages” on
page 193
Coverage For each coverable, a Collision coverage (for a LOB-specific “Coverables and
specific type of covered specific vehicle) coverages” on
loss page 193
Overview of modifying jobs 185

Content Type Definition Example from Personal LOB relationship More information
Auto
Coverage term A value that further A deductible for a given LOB-specific “Coverables and
defines or limits the collision coverage coverages” on
extent of a coverage page 193
Modifier Information relevant to An "Anti-Lock Breaks" LOB-specific “Modifiers” on
rating that is not modifier that provides page 201
necessarily tied to a 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
used to pre-qualify an policy or coverage been page 205
account or gather declined, canceled, or
additional information non-renewed during
relevant to rating the prior 3 years?"
Saying yes could
disqualify the account.
Exposure A thing that is not a Driver. This provides LOB-specific “Exposures, exclusions,
coverable but gathers information about a and conditions” on
additional information vehicle's drivers that page 211
to help rate or process can affect pricing (such
a policy as the driver's age), but
coverages are not
attached directly to any
driver.
Exclusion A limit to coverages A "Custom Equipment" LOB-specific “Exposures, exclusions,
that defines exclusion, which and conditions” on
circumstances where excludes coverage for page 211
the coverage does not damage done to
apply "aftermarket
equipment and
modifications"
Condition A contractual obligation A condition stating that LOB-specific “Exposures, exclusions,
of the insurance policy cancellation for non- and conditions” on
that are neither payment requires a 30- page 211
coverages nor day notice (and not just
exclusions a 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 145
Policy location An account location The location where a LOB-generic “Policy locations” on
associated with a policy vehicle is garaged page 146
Overview of modifying jobs

chapter 25
Lines of business

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
This topic discusses how to work with lines.
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
Coverage For each coverable, a specific type of covered loss Collision coverage (for a specific vehicle)
Lines of business 187

Type Definition Example from Personal Auto

Coverage A value that further defines or limits the extent of A deductible for a given collision coverage
term a coverage
Modifier Information relevant to rating that is not An "Anti-Lock Breaks" modifier that provides a discount
necessarily tied to a specific coverable or coverage for 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 canceled, or non-renewed during the prior 3 years?"
to rating Saying yes could disqualify the account.
Exposure A thing that is not a coverable but gathers Driver. This provides information about a vehicle's drivers
additional information to help rate or process a that can affect pricing (such as the driver's age), but
policy 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 A condition stating that cancellation for non-payment
that 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 “APIs for lines of
business” on page 365.
• For information on how to generate the endpoints for the base configuration Personal Auto product, see “The
base configuration Personal Auto product” on page 375.
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}/bind-and-issue
These endpoints are discussed in the topics on each job type, such as the “Submissions” on page 159 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
The LOB-generic endpoints are discussed in later topics in this section.
188 chapter 25: Lines of business
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 “APIs for lines of business” on page 365. 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 base configuration Personal Auto product” on page 375.
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"
},
"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.
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)


chapter 26
Coverables and coverages

This includes:
• Lines
• Coverables
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
• Policy contacts
This topic discusses how to work with coverables, coverages, and coverage terms.
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}
• PATCH /jobs/{jobId}/lines/{lineId}
• DELETE /jobs/{jobId}/lines/{lineId}
Coverables and coverages 193
• GET /jobs/{jobId}/lines/PersonalAutoLine
• PATCH /jobs/{jobId}/lines/PersonalAutoLine
• DELETE /jobs/{jobId}/lines/PersonalAutoLine
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}
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.
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"
194 chapter 26: Coverables and coverages

},
"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 215.
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}
• GET /jobs/{jobId}/lines/PersonalAutoLine/coverages
• POST /jobs/{jobId}/lines/PersonalAutoLine/coverages
• 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}
• 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:
{buildingId}/coverages
{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 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.)
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 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).
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>",
"decimalValue": "<value>",
"choiceValue": {
"code": "<valueFromPreductDefinition>"
},
"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
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"
}
}
}
}
}
}
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 215.
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 215.

chapter 27
Modifiers

This includes:
• Lines
• Coverables
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
• Policy contacts
This topic discusses how to work with modifiers.
Overview of modifiers
A modifier is a value used by the rating engine to adjust the policy premium (or some portion of it). Modifiers
capture information relevant to pricing that are not necessarily tied to specific coverage or coverable. Modifiers are
attached either to the line itself (such as a MultiPolicyDiscount modifier) or to a specific object, such as a vehicle
(such as an AntiLockBreaks discount).
Modifiers 201
Note: Advanced Product Designer does not support modifiers. However, products built through other
means may have modifiers, such as products from the original Product Designer.
LOB-endpoint pattern for modifiers

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}
◦ 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}
Specifying modifiers
Creating modifiers
When a line or modifiable object is created, a set of modifier objects are automatically created. Thus, there are no
POST /modifiers or DELETE /modifiers endpoints.
You cannot specify defaults in the product definition. Modifiers may or may not have default values:
• For Boolean modifiers, PolicyCenter defaults them 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.
They are attached either to the line itself (such as a MultiPolicyDiscount modifier) or to a specific object, such as a
vehicle (such as an AntiLockBreaks discount modifier).
Retrieving modifiers and their values

Use the following endpoints to retrieve all 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}
202 chapter 27: Modifiers

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.
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 is the 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"
},
"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}
Modifiers 203
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).
PATCH /job/v1/jobs/pc:1111/lines/PersonalAutoLine/vehicles/505/modifiers/ PAPassiveRestraint
{
"data": {
"attributes": {
"code": "driver"
}
}
}
}
Modifier validation
Default validation for modifiers
In most cases, PolicyCenter restricts the following behaviors:
• Cannot set the values for an unavailable Modifier
• Cannot set the value for the rateModifier field outside of the min/max range
• Cannot set the value for rate factors on the Modifier 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-modifiers endpoint. For more information, see “Synchronization and
deferred validation” on page 215.
reduce the need to determine if modifiers need to be synchronized.
204 chapter 27: Modifiers

chapter 28
Questions

This includes:
• Lines
• Coverables
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
• Policy contacts
This topic discusses how to work with questions.
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
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.
Questions 205
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.
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:
206 chapter 28: Questions
"<questionId>": {
"question": {
"displayName": "<displayText>"
"id": "<questionId>"
},
"questionType": {
"code": "<questionTypeCode>",
},
"choiceValue": {
},
},
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.
The first question, MovingViolations2, is a Boolean question. Its answer is true.
{
"data": {
"attributes": {
"answers": {
"MovingViolations2": {
"question": {
Questions 207
"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",
},
...
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").
...
"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.
...
"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.

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>": {
"choiceValue": {
},
},
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": {
},
"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 215.
Questions 209
reduce the need to determine if questions need to be synchronized.

chapter 29
Exposures, exclusions, and conditions

This includes:
• Lines
• Coverables
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
• Policy contacts
• Users assigned to the job
This topic discusses how to work with exposures, exclusions, and conditions.
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.
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.
Exposures, exclusions, and conditions 211
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 195.
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.
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"
}
}
212 chapter 29: Exposures, exclusions, and conditions

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

214 chapter 29: Exposures, exclusions, and conditions

chapter 30
Synchronization and deferred

validation

This includes:
• Lines
• Coverables
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
• Policy contacts
This topic discusses the need to synchronize policy data and how you can defer validation.
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
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.
Synchronization and deferred validation 215
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.
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 217.
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 219.
216 chapter 30: Synchronization and deferred validation
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

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

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.

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 219.
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
appropriate for caller applications 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 after the caller
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)
• Coverage endpoints (such as POST /jobs/{jobId}/lines/{lineId}/coverages)
• Question endpoints such as POST /job/v1/jobs/{jobId}/questions)

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
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 Authentication 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.
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 /job/{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 /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.
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
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.


chapter 31
Policy contacts

This includes:
• Lines
• Coverables
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
• Policy contacts
This topic discusses how to work with 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
Policy contacts 223
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/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}
Policy GET /policy/v1/accounts/{accountId}/contacts PolicyContact
GET /policy/v1/accounts/{accountId}/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

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}
Adding an account contact to a job

You can add an account contact to a job. When you do this, the contact is added to the underlying policy with the
APDPolicyInvoledParty role. This is a generic role that simply identifies the contact has an association with the
policy.
To associate an account contact with a job's policy, use the following endpoint:
• POST /job/v1/jobs/{jobId}/contacts
224 chapter 31: Policy 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 with the
APDPolicyInvoledParty role.
POST /job/v1/jobs/{jobId}/contacts/pc:5000
{
"data": {
"attributes": {
"accountContact": {
"id": "pc:97"
}
}
}
}
Note that, from the perspective of the job, you cannot create new contacts. You can only associate existing account
contacts to the job's policy. If the desired contact does not exist, you must first create it as an account contact and
then associate it with the job's policy. For information on creating account contacts, see “Creating account contacts”
on page 137.
Once the account contact is associated with the policy, you can modify the contact's policy roles.
• To make the contact the primary named insured on the policy, see “Primary named insured contacts” on
page 226.
• To make the contact an additional named insured on the policy, see “Adding additional named insureds” on
page 227.
PATCHing and DELETEing policy contacts

PATCHing 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.
PATCH /job/v1/jobs/pc:1001/contacts/pc:44
{
"data": {
"attributes": {
"emailAddress1": "quiltQueen71@email.com"
}
}
}
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.
DELETEing 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>
Policy contacts 225

Primary 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.
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"
}
}
}
}
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"
},
"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"
}
}
}
Policy contacts 227

PATCHing and DELETEing 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>

chapter 32
Policy locations

This includes:
• Lines
• Coverables
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
• Policy contacts
This topic discusses how to work with policy locations.
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 229

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": {
"code": "CA"
},
230 chapter 32: Policy locations

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

232 chapter 32: Policy locations

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


chapter 33
Working with product definitions
he Product Definition API supports a set of endpoints for querying products, lines, and reference code data.
Products and lines
The product and line endpoints provide read-only access to product data models.
The /productdefinition/v1/products/* endpoints can be used to query products and their associated lines and
questions.
The /productdefinition/v1/lines/* endpoints can be used to query lines and their associated coverables,
coverages, exposures, and questions.
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
/productdefinition/v1/reference-data/uw- Underwriting issue codes UWIssueType UWIssueType

issue-types
/productdefinition/v1/reference-data/wc- Workers' Comp class WCClassCode WCClassCode

class-codes codes
/productdefinition/v1/reference-data/wc-fed- Workers' Comp federal WCFedLiabClassCode WCFedLiabClassCode
liab-class-codes liability class codes
Working with product definitions 237

238 chapter 33: 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
• periodStart and periodEnd
• producerCode
• quoteType
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
◦ This can be changed to the ID of another location on the job
• termType
◦ A value from the TermType typelist
PATCHing jobs 239
• 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": {
}
}
}
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"
}
}
}
}
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 261.
240 chapter 34: PATCHing jobs

Part 5
Business flows: Job support
The following topics discuss how caller applications can use PolicyCenter functionality that supports multiple types
of jobs. This includes:
• Job searches
• Underwriting issues
• Quoting (including multi-version quoting and cost overrides)
• Policy compare
• Out-of-sequence conflicts
chapter
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 policy.
• You can compare an unbound job to the policy it is based on.
• You can compare jobs for the same policy.
Cloud API also supports the ability to retrieve this information.
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 relevant job wizard. 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 retrieve this information from Cloud API, use the following endpoint:
• POST /job/v1/jobs/{jobId}/review-diffs
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
◦ 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".
Comparing jobs 243
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:Sm81CxKtBiMzNp__AXUjk 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.
The basedOnJob section

For our example, the basedOnJob information could look like this:
"basedOnJob": {
"displayName": "47586734721",
"id": "pc:Sm81CxKtBiMzNp__AXUjk",
"type": "Job",
Comparing jobs
"uri": "/job/v1/jobs/pc:Sm81CxKtBiMzNp__AXUjk"
},
The diffTree Policy Info section

For our example, the first children node details changes at the policy level. (Note that the label, which identifies the
user interface text to label the information, appears after the children node.)
"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 our example, there is a Vehicles node as shown below. 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": [
{
"entity": {
"id": "38"
},
"label": "Collision"
},
...
],
"label": "Coverages"
},
{
"children": [
{
"entity": {
"displayName": "Anti Theft Discount (California)",
"id": "57"
},
"label": "Anti Theft Discount (California)"
},
...
],
"label": "Modifiers"
},
{
"entity": {
"id": "11"
},
"label": "Assigned Driver: Ray Newton"
}
Comparing jobs 245

],
"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": [
{
"entity": {
"id": "4"
},
"label": "Collision"
},
...
],
"label": "Coverages"
},
{
"children": [
{
"entity": {
"displayName": "Anti Theft Discount (California)",
"id": "6"
},
"label": "Anti Theft Discount (California)"
},
...
],
"label": "Modifiers"
},
{
"entity": {
"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 our example:
• "Underinsured Motorist - Property Damage" is being added
• "Mexico Coverage - Limited" is being removed
{
"children": [
{
"children": [
{
"entity": {
"displayName": "Mexico Coverage - Limited",
Comparing jobs
"id": "5"
},
"label": "Mexico Coverage - Limited Coverage"
}
],
"label": "Mexico Coverage - Limited"
},
{
"children": [
{
"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 in PolicyCenter in Cloud API

To retrieve this information 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, which details the differences between the
two jobs.
Structure of the CompareJobAttributes resource

The CompareJobAttributes resource has the following structure:
• diffTree
◦ Information about the differences between the selected jobs
Comparing jobs 247
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").
• 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 that is being added by the job.
◦ Remove - The node defines an entity present in 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 using Gosu), and can only be done for certain types of jobs, such as General Liability and Worker's
Compensation.
Comparing jobs
chapter 35
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 contingency associated with the given job.
GET /policies/{policyId}/contingencies Retrieve all contingencies for the given policy.
GET /policies/{policyId}/contingencies/ Retrieve the given contingency associated with the given
{contingencyId} policy.
Contingencies use the same schema, whether they are associated with jobs or 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
{
...
Contingencies 249
"attributes": {
"action": {
"code": "ChangeRetroactively",
"name": "Change policy retroactively"
},
"actionStartDate": "2021-11-04T00:00:00.000Z",
"actionStarted": false,
"createDate": "2021-11-04T23:26:33.069Z",
"createUser": {
"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
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
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.
Activities, documents, and notes use the same schema, whether they are primarily associated with account, jobs,
policies, or contingencies.
For more information on working with activities, documents, or notes, see the following:
• “Activities” on page 281
• “Documents” on page 289
• “Notes” on page 295
250 chapter 35: Contingencies

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

At a minimum, a contingency must specify:
• 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
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
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
{contingencyId}/documents the given policy.
POST /policies/{policyId}/contingencies/ Create a note associated with the given contingency on the
{contingencyId}/notes given policy.
Contingencies 251
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 281
• “Documents” on page 289
• “Notes” on page 295
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 Authentication 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 Authentication Guide.
252 chapter 35: Contingencies

chapter 36
Policy and job search
The Job and Policy APIs provide endpoints that can be used to search for jobs or policies, respectively:
• /job/v1/search/jobs
• /policy/v1/search/policies
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 (job search only): 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 or policy
• inForceOn (policy search only): A date string (YYYY-MM-DD) specifying a date on which the policy is in force
• jurisdiction.code: A jurisdiction code
• postalCode: A postal code associated with a job or policy
• product.id: A product ID for the LOB
• state.code: A state associated with a job or policy
• street: A street address associated with a job or policy
To get a count of the total number of matches for the search, add the query parameter &includeTotal=true to the
request. For more information on controlling pagination, see “Controlling pagination” on page 56.
Policy and job search 253

254 chapter 36: Policy and job search

chapter 37
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"
},
{
}
],
"entity": {
"displayName": "Bill Preston",
"id": "pc:703",
"uri": "/job/v1/jobs/pc:204/contacts/pc:703"
Out-of-sequence conflicts 255

},
"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"
]
}
256 chapter 37: Out-of-sequence conflicts

}
}
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": [
{
},
{
}
],
"entity": {
"displayName": "Bill Preston",
"id": "pc:703",
"uri": "/job/v1/jobs/pc:204/contacts/pc:703"
},
"id": "b0aca4b",
"yourValue": "01/01/1980"
},
{
"conflictValues": [
{
"displayValue": "Address Line 1; Future Change",
},
{
"displayValue": "Address Line 1; Future Change",

}
],
"entity": {
"displayName": "1: Address Line 1; OOS Change, CA",
"id": "201",
"uri": "/job/v1/jobs/pc:204/locations/201"
},
"field": "addressLine1Internal",
"id": "df78662",
"originalValue": "",
"yourValue": "Address Line 1; OOS Change"
},
{
"conflictValues": [
{
"displayValue": "2",
}
],
"entity": {
"displayName": "1: Address Line 1; OOS Change, CA",
"id": "201",
"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": [
{
"id": "b0aca4b",
"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",
},
{
"id": "df78662",
},
{
"id": "47761d4",
"resolution": "discardYours"
}
]
}
}
}
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".


chapter 38
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)
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
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}
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"
}
},
. . .
Quoting 261
}
],
. . .
}
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.
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": {
262 chapter 38: Quoting

"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:
• /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
Quoting 263
◦ 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
◦ 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.
(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 265

chapter 39
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.
Underwriting issues 267
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).
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 of
{uwIssueId}/history 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- A collection of underwriting issues associated with the given policy
issues
GET /policy/v1/policies/{policyId}/uw- The specified underwriting issue

issues/{uwIssueId}
GET /policy/v1/policies/{policyId}/uw- A collection of UWIssueHistory resources that trace the state history of the
issues/{uwIssueId}/history specified underwriting issue.
Creating underwriting issues

To create an underwriting issue, use the following endpoint:
• POST /job/v1/jobs/{jobId}/uw-issues

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'"
268 chapter 39: Underwriting issues

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",
"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">
<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 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"
}
}
}
}
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.
• 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 under- String Value
default writing 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 approvalBlockingPoint From the UWIssueBlockingPoint typelist Through
job 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
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
• 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 281.
For more information on specifying note attributes, see “Notes” on page 295.
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
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": {
}
},
"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 281.
For more information on specifying note attributes, see “Notes” on page 295.
Referral reasons
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


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 268.
As is the case with underwriting issues, some referral reasons require other values, depending on the issueType. For
example:
• 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 271.
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".
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".


Part 6
Business flows: Framework APIs
The following topics discuss how caller applications can initiate business flows related to the Common API and the
Admin API. This includes:
• The Common API
◦ Working with activities
◦ Working with documents
◦ Working with notes
• The Admin API
◦ Working with users and groups
◦ Working with organizations
◦ Working with producer codes
chapter 40
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 system 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 281
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 the system APIs, 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 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 The activity importance (as reflected on the Typically comes from the activity
(ImportanceLevel) 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 (Priority) The activity's priority Typically comes from the activity
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 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.
POST /account/v1/accounts/pc:10/activities
{
"data": {
"attributes": {
282 chapter 40: Activities

"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.
POST /account/v1/accounts/pc:10/activities
{
"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 the system APIs, 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 the system APIs 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
queueId string The ID of the queue to assign the activity to
role TypeKeyReference (UserRole) The role on the parent object that identifies the user to assign the activity to
userId string The ID of the user to assign the activity to
The Assignee resource must specify an assignment option. It cannot be empty.

Activities 283
Assignment examples
When assigning activities to users, the user must be active and must have the "own activity" system permission.
Assigning to a specific group (and user)

The following payload assigns activity xc:1 to group demo_sample:31 and user demo_sample:1.
POST /common/v1/activities/xc:1/assign
{
"data": {
"attributes" : {
}
}
}
The following payload assigns activity xc:1 to group demo-sample:31. Because no user has been specified,
PolicyCenter will execute assignment rules to assign the activity to a user in group demo-sample:31.
{
"data": {
"attributes" : {
"groupId": "demo_sample:31"
}
}
}
Note that there is currently no endpoint that returns groups or group IDs. To assign activities to a specific group, the
caller application must determine the group ID using some method other than a groups system API.
Assigning to a specific queue

The following payload assigns activity xc:1 to queue cc:32. Every queue is associated with a single group, so the
activity will also be assigned to that group. Users in that group who have access to this queue can then manually
take ownership of the activity.
{
"data": {
"attributes" : {
"queueId": "cc:32"
}
}
}
Note that there is currently no endpoint that returns queues or queue IDs. To assign activities to a queue, the caller
application must determine the queue ID using some method other than a queues system API.
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.)
• 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 system
API 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.
{
"data": {
"attributes" : {
"role" : {
"code" : "Underwriter"
}
}
}
}
Using automated assignment

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

When 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 /assignee endpoints:
Endpoint Returns
/common/v1/activity/{activityId}/assignee 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 /assignee endpoint.
GET /common/v1/activities/pc:301/assignees
{
"count": 5,
"data": [
{
"attributes": {
"name": "Creator",
"role": {
"code": "Creator",
"name": "Creator"
}
Activities 285
}
},
{
"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 corresponding action. Activities have a
mandatory Boolean field. If this is set to true, the activity cannot be skipped.
The following payload skips activity xc:1.
POST /common/v1/activities/xc:1/skip
<no request payload>

The following payload skips activity xc:1 and creates a note.

POST /common/v1/activities/xc:1/skip
{
"included": {
"Note": [
{
"attributes": {
"body": "This activity was skipped by a system API call."
},
"method": "post",
"uri": "/common/v1/activities/xc:1/notes"
}
]
}
}
Additional activity functionality

The Common API contains these additional activity endpoints.
PATCHing activities
• PATCH /activities/{activityId}
Working with activity notes

• GET /activities/{activityId}/notes
• POST /activities/{activityId}/notes
For more information on notes, see “Notes” on page 295.
Activities 287

chapter 41
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 system API perspective,
PolicyCenter documents are always attached to accounts, jobs, or policies. ContactManager documents are always
attached 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 lacks the full range of features found in a
Document Management System, such as versioning.
Documents can exist in an InsuranceSuite application with metadata but no contents. For example, this may be
appropriate when a document is a physical piece of paper retained by the insurer. The insurer may want to track the
Documents 289
existence of the document and metadata about the document, even though the contents are not in the Document
Management System.
Documents cannot exist in an InsuranceSuite application with contents but no metadata.
Querying for document information

Querying for document metadata
You can use the following endpoints to GET 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
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
{
"data": {
"attributes": {
290 chapter 41: Documents

"contents": "REVWIEJVSUxEDQoNCklmIHRoZXJlIGlzIG9ubHkgYSB2aXN1YWxp
emVkIHByb2R1Y3QNCiAgQU5EIHRoZSAiRW5hYmxlZCBmb3IgUmVzdCBBUEkiIGZpZWxkIGlzIGlua
XRpYWxseSBzZXQgdG8gRW5hYmxlZA0KICBBTkQgeW91IGNoYW5nZSB0aGUgZmllbGQgdG8gRGlzYW
JsZWQNCiAgVEhFTiB0aGUgcHJvZHVjdCBpcyBpbW1lZGlhdGVseSB1bmF2YWlsYWJsZSB0byB0aGU
gc3lzdGVtIEFQSXMNCg0KSWYgdGhlcmUgaXMgYSB2aXN1YWxpemVkIHByb2R1Y3QgYW5kIGEgZmlu
YWxpemVkIHByb2R1Y3QNCiAgQU5EIHRoZSAiRW5hYmxlZCBmb3IgUmVzdCBBUEkiIGZpZWxkIGlzI
GluaXRpYWxseSBzZXQgdG8gRW5hYmxlZA0KICBBTkQgeW91IGNoYW5nZSB0aGUgZmllbGQgdG8gRG
lzYWJsZWQNCiAgVEhFTiB0aGUgZmluYWxpemVkIHByb2R1Y3QgaXMgaW1tZWRpYXRlbHkgYXZhaWx
hYmxlIHRvIHRoZSBzeXN0ZW0gQVBJcw0KDQpDVVNUT01FUiBCVUlMRA0KDQpJZiB0aGVyZSBpcyBv
bmx5IGEgdmlzdWFsaXplZCBwcm9kdWN0DQogIEFORCB0aGUgIkVuYWJsZWQgZm9yIFJlc3QgQVBJI
iBmaWVsZCBpcyBpbml0aWFsbHkgc2V0IHRvIEVuYWJsZWQNCiAgQU5EIHlvdSBjaGFuZ2UgdGhlIG
ZpZWxkIHRvIERpc2FibGVkDQogIFRIRU4gdGhlIHByb2R1Y3QgaXMgaW1tZWRpYXRlbHkgdW5hdmF
pbGFibGUgdG8gdGhlIHN5c3RlbSBBUElzDQooSSBhc3N1bWUgdGhpcyBpcyB0aGUgc2FtZSBhcyAN
Cg0KSWYgdGhlcmUgaXMgYSB2aXN1YWxpemVkIHByb2R1Y3QgYW5kIGEgZmluYWxpemVkIHByb2R1Y
3QNCiAgQU5EIHRoZSAiRW5hYmxlZCBmb3IgUmVzdCBBUEkiIGZpZWxkIGlzIGluaXRpYWxseSBzZX
QgdG8gRW5hYmxlZA0KICBBTkQgeW91IGNoYW5nZSB0aGUgZmllbGQgdG8gRGlzYWJsZWQNCiAgVEh
FTiB0aGUgZmluYWxpemVkIHByb2R1Y3QgaXMgaW1tZWRpYXRlbHkgYXZhaWxhYmxlIHRvIHRoZSBz
eXN0ZW0gQVBJcw==",
"responseMimeType": "text/plain"
},
...
POSTing documents
You can use the following to POST documents.
• /account/v1/accounts/{accountId}/documents
• /job/v1/jobs/{jobId}/documents
• /policy/v1/policies/{policyId}/documents
• (ContactManager) /contact/v1/contacts/{contactId}/documents
◦ In ContactManager, documents can be posted only to contacts with the "vendor" tag.
FormData objects
For most Cloud API resource, the request object is constructed as a body with a single string of JSON text.
However, this format is not sufficiently robust for documents. When working with documents, the caller application
must send two sets of data: the document metadata and the document contents. This is accomplished using
FormData objects.
FormData is an industry-standard interface that constructs an object as a set of key/value pairs. When a caller
application is constructing a POST /documents call, the request object must be a FormData object with the
following keys:
• metadata, whose value is a JSON string identifying the document metadata
• content, whose value is the contents of the document (and whose format varies based on the document type)
Two approaches to POSTing documents
There are two ways that a caller application can create a document:
1. POST both the document metadata and content to PolicyCenter using a /documents endpoint. In this
approach:
• 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).
2. Add the document to the Document Management System directly, and then POST the document metadata to
PolicyCenter. In this approach:
• The POST /documents call must provide any required information that comes from the Document
Management System in the metadata (such as the document's DocUID).
Documents 291

When POSTing a document:
• The metadata JSON must include the following fields:
◦ name
◦ status (a typecode from the DocumentStatusType typelist)
◦ type (a typecode from the DocumentType typelist)
• The content value is not required. For example, it may be appropriate to omit content when the document is a
physical piece of paper that does not exist in the Document Management System, or when the caller application
has added the document to the Document Management System directly.
Examples of POSTing documents

The following is an example of POSTing a "Property Assessment Report.pdf" file for account pc:10 through
PolicyCenter.
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 documents using Postman

About this task
From Postman, you can POST documents using FormData objects. When doing so, both the metadata and content
must be stored in separate files referenced by the Postman call.
Note: Every POST /documents endpoint supports the ability to receive the metadata as either a string
or a file. However, there is a known issue with Postman which prevents the sending of metadata as a
string. When using Postman, the metadata can be sent only as file. This is described in the following
procedure. (Client applications other than Postman may support both string and file.)
Procedure
1. Identify the files needed for the FormData object. This includes:
• A JSON file that contains the metadata. (The file extension must be .json.)
• The document file that has the content.
3. Under the Untitled Request label, select POST.
• For example, to POST a document to 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.
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.
PATCHing documents
You can use the following to PATCH documents.
• /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 document metadata

Every PATCH /{documentId} call must include a metadata key/value pair, even if you want to modify only the
content.
• If you want to modify the metadata, specify the fields to modify in the JSON referenced by the metadata key.
• If you do not want to modify the metadata, have the metadata key reference a payload with no attribute values,
as shown below:
{
"data": {
"attributes": {
}
}
}
PATCHing document content

A PATCH /{documentId} call is not required to include a content key/value pair. If no content is specified, the
PATCH will update the document metadata only.
PATCHes to content are destructive, not additive. If you specify content, the new content replaces the previous
content entirely.
Examples of PATCHing documents

The following is an example of PATCHing only the metadata for document xc:101. In this example, the document
status is changed to final.
PATCH /common/v1/documents/xc:101
Metadata:
{
"data": {
"attributes": {
"status": {
"code": "final"
}
}
}
}
Documents 293
(No contents included with the API call)
The following is an example of PATCHing only the contents for document xc:101. Presumably, the contents of
"Property Assessment Report.pdf" are different than the current contents of document xc:101.
Metadata:
{
"data": {
"attributes": {
}
}
}
Contents:
The following is an example of PATCHing both the metadata for document xc:101 and the content.
Metadata:
{
"data": {
"attributes": {
"status": {
"code": "final"
}
}
}
}
Contents:
DELETEing documents
You can use the following to DELETE documents.
• /common/v1/documents/{documentId}

chapter 42
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 system APIs.
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

You can use the following endpoints to GET 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
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.
Notes 295
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 (NoteSecurityType) The note's security type NULL
subject string The note's subject NULL
topic Typekey (NoteTopicType) 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'." ,
"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
{
"data": {
296 chapter 42: Notes

"attributes": {
"body": "This activity was completed during a telephone call with the insured on 11/17."
}
}
}
Additional notes functionality

The Common API contains these additional notes endpoints.
PATCHing notes
• PATCH common/v1/notes/{noteId}
DELETEing notes
• DELETE common/v1/notes/{noteId}
Notes 297
298 chapter 42: Notes

chapter 43
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 Authentication Guide.
Querying for users

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).
GET /admin/v1/users/pc:S-sAtIMQDbK0z3b2E7Mvw
{
"data": {
"attributes": {
"active": true,
"externalUser": false,
"firstName": "Alice",
"groups": [
{
"displayName": "Los Angeles Branch UW",
"id": "pc:SSXQ8EaLxQq4LZ33Ia76r"
},
{
"displayName": "Eastern Region Underwriting",
"id": "pc:SVZTqTgdrHJKYQV9aGCbN"
}
Users and groups 299

],
"id": "pc:S-sAtIMQDbK0z3b2E7Mvw",
"lastName": "Applegate",
"organization": {
"displayName": "Enigma Fire & Casualty",
"id": "systemTables:1",
"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:
• 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.

300 chapter 43: Users and groups
POST /admin/v1/users
{
"data": {
"attributes": {
"active": true,
"displayName": "",
"externalUser": false,
"id": "pc:SatEdbNuwVSfc2BvbG4g4",
"organization": {
"displayName": "Enigma Fire & Casualty",
"id": "systemTables:1",
"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
• Roles: audit examiner (audit_examiner) and audit supervisor (audit_supervisor)
{
"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 305.
• For more information on working with authority profiles, see “Authority profiles” on page 308.
• For more information on working with a user's producer codes, see .
Assigning a user to a group

You cannot assign a user to a group using the /admin/v1/users endpoint. You must use the /admin/v1/groups/
{groupId}/users endpoint. For more information, see “Assigning users to groups” on page 303.
Updating users
Use the following endpoint to modify an existing user:
• PATCH /admin/v1/users/{userId}
For example, the following request updates the first name of user xc:2156
PATCH /admin/v1/isers/xc:2156
{
"data": {
"attributes": {
"firstName": "Alex"
}
}
}
Groups
A group is a set of users who represent a single business unit or who are assigned a single body of work.
You cannot create groups through Cloud API. However, you can retrieve information about groups, and you can
assign users to groups and unassign them from groups.
Querying for groups

To retrieve information about a group, use the following endpoints:
• GET /admin/v1/groups
• GET /admin/v1/groups/{groupId}
For example, the following is the snippet of the response payload when retrieving the information for group
demo_sample:31.
GET /admin/v1/users/demo_sample:31
{
"data": {
"attributes": {
"displayName": "Alexandria Branch",
"groupType": {
"code": "branch",
"name": "Branch office"
},
"name": "Alexandria Branch",
"parent": {
"displayName": "Eastern Region",
"type": "Group",
"uri": "/admin/v1/groups/demo_sample:29"
},
"securityZone": {
"displayName": "Auto and Property",
"id": "default_data:1"

},
"supervisor": {
"displayName": "Sue Smith",
"type": "User",
}
},
...
}
}
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
{
"count": 12,
"data": [
{
"attributes": {
"id": "cc:SfZwdri9ldAAUgR46xZT7",
"manager": false,
"member": true,
"user": {
"type": "User",
}
},
...
},
{
"attributes": {
"id": "cc:SZPhG_CUIA3E1sO2AiZ_s",

"manager": false,
"member": true,
"user": {
"displayName": "Betty Baker",
"type": "User",
}
},
...
},
...
Adding a user to a group

To add a user to a group, use the following endpoint:
• POST /admin/v1/groups/{groupId}/users
In the request, you must specify the user to be added to the group. You can optionally specify other attributes. If you
do not, the following default values are used:
• member: true
• manager: false
• loadFactor: null
For example, the following request adds user demo_sample:18 to group demo_sample:31.
POST /admin/v1/groups/demo_sample:31/users
{
"data": {
"attributes": {
"user": {
}
}
}
}
This assigns user demo_sample:18 to group demo_sample:31 as a member. The user is not a manager of the group
and has a null load factor. (If a field’s value is null, the field is not included in Cloud API responses.)
Modifying information about a user’s GroupUser assignment

To modify a user’s GroupUser assignment information, use the following endpoint:
• PATCH /admin/v1/groups/{groupId}/users/{groupID}
For example, suppose that user demo_sample:18 has been added to group demo_sample:31 through a GroupUser
object whose id is xc:55. This user is a member of the group and not a manager of the group. The following
PATCHes the GroupUser assignment so that the user is a manager of the group and not a member. (They can view
work assigned to other users in the group, and they will not have work assigned to them.)
PATCH /admin/v1/groups/demo_sample:31/users/xc:55
{
"data": {
"attributes": {
"manager": true,
"member": false
}
}
}
Removing a user from a group

To remove a user from a group, you must delete the corresponding GroupUser assignment. To do this, use the
following endpoint:
• DELETE /admin/v1/groups/{groupId}/users/{groupUserId}
For example, suppose that user demo_sample:18 has been added to group demo_sample:31 through a GroupUser
object whose id is xc:55. The following request removes user demo_sample:18 to group demo_sample:31.
DELETE /admin/v1/groups/demo_sample:31/users/xc:55
<no request body>
User roles
A system permission is a granular permission that identifies something a user can view, edit, create, or otherwise
work with.
A user role is a named group of system permissions. User roles simplify the work of granting access by allowing a
set of related system permissions to be assigned to a user. (Note that in most Guidewire documentation, user roles
are referred to simply as "roles". The Cloud API documentation uses the term "user role" to help distinguish them
from "API roles", which is a feature with a similar purpose but different underlying functionality.)
Querying for user roles

To retrieve information about user roles, use the following endpoints:
• GET /admin/v1/roles
• GET /admin/v1/roles/{roleId}
For example, the following is the snippet of the response payload when retrieving the first four roles in the base
configuration.
GET /admin/v1/roles?pageSize=4
{
"count": 5,
"data": [
{
"attributes": {
"carrierInternal": true,
"description": "Permissions for account admin",
"displayName": "Account Manager",
"id": "account_manager",
"name": "Account Manager"
}
},
{
"attributes": {
"description": "All permissions related to activity rules",
"displayName": "Activity Rules Admin",
"id": "activity_rules_admin",
"name": "Activity Rules Admin"
}
},
{
"attributes": {
"description": "Permissions to edit activity rules",
"displayName": "Activity Rules Editor",
"id": "activity_rules_editor",
"name": "Activity Rules Editor"
}
},
{
"attributes": {
"description": "Permissions to view activity rules",
"displayName": "Activity Rules Viewer",
"id": "activity_rules_viewer",
"name": "Activity Rules Viewer"
}
}
]
}

Querying for permissions in a user role

To retrieve information about the permissions in a given user roles, use the following endpoints:
• GET /admin/v1/roles/{roleId}/permissions
• GET /admin/v1/roles/{roleId}/permissions/{permissionId}
For example, the following is the snippet of the response payload when retrieving the first three permissions
associated with a "claims_adjuster" role:
GET /admin/v1/roles/claims_adjuster/permissions
{
"count": 25,
"data": [
{
"attributes": {
"id": "sample_data:213",
"permission": {
"code": "lvprint",
"name": "Print listviews"
}
},
...
},
{
"attributes": {
"permission": {
"code": "searchpols",
"name": "Search related policies"
}
},
...
},
{
"attributes": {
"permission": {
"code": "actview",
"name": "View activities"
}
},
...
},
...
Creating user roles

To create a role through Cloud API, you must use multiple endpoints. The role itself is created using the /roles
endpoint. Permissions are added to the role using the /permissions endpoint.
Create the role

To create a role, use the following endpoint:
• POST /admin/v1/roles
For new roles, you must specify the following:
• name
• roleType
roleType must be a value from the RoleType typelist. The following table summarizes the role types available in
InsuranceSuite.
Name Code Description Application

User Role user Role associated with Users All InsuranceSuite applications
Producer Code Role producercode Role associated with Producer Codes PolicyCenter only

Name Code Description Application

User Producer Code Role userproducercode Role associated with Users and Producer PolicyCenter only
Codes
For example, the following creates a new user role for users named "finance_admin".
POST /admin/v1/roles
{
"data": {
"attributes": {
"roleType": {
"code": "user"
},
"name": "finance_admin"
}
}
}
Add permissions to the role

To add a permission to a role, use the following endpoint:
• POST /admin/v1/roles/{roleId}/permissions
You must specify the permission to be added by its code from the SystemPermissionType typelist.
For example, the following adds the notecreate permission to the user role with id xc:222.
POST /admin/v1/roles/xc:222/permissions
{
"data": {
"attributes": {
"permission": {
"code": "notecreate"
}
}
}
}
There is no way to specify multiple permissions in a single call to the /permissions endpoint. You must invoke
the /permissions endpoint once for each permission to be added to a role.
Creating user roles with permissions in a single call

You can create a user role and one or more permissions for the role in a single call using request inclusion. In this
case, the name of the included resource is RolePermission. For more information on request inclusion, see
“Request inclusion” on page 95.
For example, the following call creates a user role with one permission.
POST /admin/v1/roles
{
"data": {
"attributes": {
"roleType": {
"code": "user"
},
"name": "finance_admin"
}
},
"included": {
"RolePermission": [
{
"attributes": {
"permission": {
"code": "noteview"
}
},
"method": "post",

"uri": "/admin/v1/roles/this/permissions"
}
]
}
}
Updating user roles

Use the following endpoints to modify an existing role.
PATCH /admin/v1/roles/{roleId} Modify attributes about the role, such as its name or
description
DELETE /admin/v1/roles/{roleId}/permissions/ Remove a permission from a role
{permissionId}
DELETE /admin/v1/roles/{roleId} Delete a role
Example of PATCHing a role

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

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

The following request deletes role xc:222.
DELETE /admin/v1/roles/xc:222
<no request body>
You cannot a delete a role if it is associated with one or more users.
Authority 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)
• 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",
"name": "Underwriter 1"
}
},
{
"attributes": {
"description": "Underwriter 2",
}
},
{
"attributes": {

"description": "Underwriter Manager",

"displayName": "Underwriter Manager",
"id": "pc:SeOY1PmQwKcwQnuWvmCOy",
"name": "Underwriter Manager"
}
},
{
"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)
{
"data": {
"attributes": {
"firstName": "Devon",
"lastName": "Byrne",
"username": "dbyrne",
"roles": [
{
"id": "underwriter"
}
],
{
"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": {

{
},
{
}
]
}
}
}
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": {
}
}
}
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
"data": {
"attributes": {
"approveAnyValue": false,
"comparator": {
},
"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",
"code": "Unformatted",
"name": "Unformatted"
}
},
},
{

"attributes": {
"checkingSet": {
"code": "Manual",
"name": "Manual"
},
"code": "TSTManualMonetaryAmount",
"comparator": {
},
"description": "Test manually triggered issue with monetary amount format",
"name": "Test manually triggered issue with monetary amount format",
"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">
<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">
<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"

valueFormatterType Additional required field Example
MonetaryAmount moneyValue "moneyValue": {

"amount": "200000",
"currency": "usd"
}
Number decimalValue "decimalValue": "4"
StateSet stateSetValue "stateSetValue": {

"inclusionType": "exclusive",
"states": ["CA","OR"]
}
Unformatted none
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.
issueType is ClaimTotalIncurred. This issue type is monetary amount, so there is an additional moneyValue
attribute that specifies $200,000 USD.
{
"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.
issueType is IncidenceOfClaims. This issue type is decimal, so there is an additional decimalValue attribute that
specifies 4.
{
"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:
◦ 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
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.
{
"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 inclusion” on page 95.
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"
}
]
}
}
c_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}
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>

chapter 44
Organizations
In the context of the system APIs, an organization represents a third-party entity that supports the insurer's business,
such as a producer.
With the Admin API, callers can create, update, and retrieve organization data through the /admin/v1/
organizations endpoints. Typically, internal services associated with administrator, auditor, or underwriter roles
are authorized to access the /organizations endpoints.
Querying for organizations

Authorized internal users can query for organizations. Callers can use the following endpoints to GET organization
resources:
• GET /admin/v1/organizations: Returns all organizations that are visible to the caller
• GET /admin/v1/organizations/{organizationId}: Returns the organization with the given ID
Creating organizations
Authorized internal users can create organizations. To create an organization, callers can submit a POST request to
the /admin/v1/organizations endpoint.
At minimum, the request body must contain the following fields:
• name: Organization name
• type.code: Organization type, from the BusinessType typelist
Optionally, the groupDescription field can be included (why?).
If the organization represents a producer, then the producerStatus.code field must also be included in the request.
This field takes a value from the ProducerStatus typelist. Optionally, the tier.code field can also be included for
producer organizations, and this field takes a value from the Tier typelist.
{
"data": {
"attributes": {
"name": "#(args.name)",
"producerStatus": {
"code": "Active"
},
"type": {
"code": "agency"
}
}
Organizations 317
}
}
Updating organizations
Authorized internal users can update organizations. To update an organization, callers can submit a PATCH request
to the /admin/v1/organizations/{organizationId} endpoint.
318 chapter 44: Organizations

chapter 45
Producer codes
In PolicyCenter, a producer refers to any third party who brings business to the insurer, such as an agent or broker. A
producer code is an identifier used in Guidewire systems to reference a specific producer.
With the Admin API, callers can create, update, and retrieve producer code data through the /admin/v1/producer-
codes endpoints. Typically, internal services associated with administrator or underwriter roles are authorized to
access the producer-codes endpoints.
Querying for producer codes

Authorized internal users can query for producer codes. Callers can use the following endpoints to GET producer
code resources:
• GET /admin/v1/producer-codes: Returns all producer codes
• GET /admin/v1/producer-codes/{producerCodeId}: Returns a resource for the given producer code
• GET /admin/v1/organizations/{organizationId}/producer-codes: Returns all producer codes associated
with the given organization
• GET /admin/v1/organizations/{organizationId}/producer-codes/{producerCodeId}: Returns a
resource for the given producer code associated with the given organization
Alternatively, callers can use the Account API to retrieve producer codes through the /account/v1/producer-
codes endpoint. Calls to this endpoint return a collection of producer codes that are available to the caller. This
endpoint is useful when creating policy submissions.
Creating producer codes

Authorized internal users can create producer codes. To create a producer code, callers can submit a POST request to
the /admin/v1/producer-codes endpoint. At minimum, the request body must contain the following fields:
• code: The public code for the producer
• organization.id: The ID for the producer organization
• roles: An array of one or more roles associated with the producer. Each role is an object containing an id field
associated with a valid value.
{
"data": {
"attributes": {
"code": "301-008578",
"organization": {
"id": "pc:4"
Producer codes 319

},
"roles": [
{
"id": "producer"
}
]
}
}
}
The request body can also contain the following optional fields:
• address: An Address resource
• appointmentDate: A UTC timestamp indicating appointment date
• branch.id: The ID for the branch office
• description: A string
• parent.id: The ID for the parent organization
• preferredUnderwriter.id: The ID for the preferred underwriter
• producerStatus: The status of the producer
• terminationDate: A UTC timestamp indicating termination date
Updating producer codes

Authorized internal users can update producer codes. To update a producer code, callers can submit a PATCH
request to the /admin/v1/producer-codes/{producerCodeId} endpoint.
Managing a user's producer codes

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 through Cloud API. As of this release, there are no endpoints for managing
the association between producer codes and groups.
The UserProducerCode 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. When you call an endpoint that ends with "/{userId}/producer-codes ", you are retrieving, creating, or
modifying instances of UserProducerCode. Note the following:
• The id field in a UserProducerCode instance is the id of the association.
• When you create or delete a UserProducerCode instance, you are not creating or deleting producer codes. You
are only creating or deleting associations between users and producer codes.
The UserProducerCode endpoints can be used only on users that are subject to producer code security.
Querying for a user's 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}
320 chapter 45: Producer codes
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"
}
]
}
...
Associating producer codes with users

Creating an association
To associate a producer code with a user, use the following endpoint:
• POST /admin/v1/users/{userId}/producer-codes
The only required field is the id of the producer code to be associated with the user.
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"
}
}
}
}
Deleting an association
To remove the association between a producer code and a user, use the following endpoint:
• DELETE /admin/v1/users/{userId}/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>
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"/>
Producer codes 321

For details on PolicyCenter configuration, see the Configuration Guide.
322 chapter 45: Producer codes

Part 7
Configuring Cloud API
The system APIs in InsuranceSuite Cloud API have a set of default behaviors in the base configuration. However,
through configuration, their behaviors can be modified.
The following topics discuss how insurers can configure system API behavior. This includes:
• Configuring schemas
• Obfuscating personally identifiable information (PII)
• Generating LOB-specific APIs
chapter 46
Configuring schemas
Within the context of REST, a schema is a definition of the structure of a type of resource. Resources are analogous
to OOP objects. They collect data that are part of either a REST request or a REST response. Cloud API uses
resource definition files to define the resource structure and the way in which information is mapped between the
resource and the corresponding data model entity.
This topic describes how to configure the different types of resource definition files.
• “Tutorial: Data mapping for new properties” on page 335
• “Tutorial: Extending a data model entity and its API resource” on page 343
Overview of resource definition files

Within the context of REST, a resource is a collection of data that is part of either a REST request or a REST
response. For example, when you create an activity through a REST endpoint:
• The request includes a resource that specifies information about the activity to be created (such as the activity's
subject and due date).
• The response includes a resource that specifies information about the activity that was created (such as the
activity's subject and due date, as well as information created by the application, such as the activity's ID and
status.)
Within Cloud API, every resource is defined in up to there are three files:
• The schema file, which defines the structure of the schema used by element and collection resources.
• The mapping file, which defines how information is mapped from the data model entity to the element resource.
◦ This information is used for GETs, and for the responses of POSTs and PATCHes.
• The updater file, which defines how information is mapped from the element resource to the data model entity.
◦ This information is used for POSTs and PATCHes.
There are two other files which are related to schema functionality.
• The swagger file, which defines the endpoints themselves. The definition of each endpoint includes:
◦ The endpoint path (such as /common/v1/activities/{activityId})
◦ The operations allowed on the path (such as GET or PATCH)
◦ The resourceType of the endpoint (such as Activity) and any associated child resources.
• The apiconfig file, which defines the default sort, if any, for resource collections.
Configuring schemas 325
Resource definition file architecture

The following diagram depicts the resource definition file architecture for the Activity data model entity.
• The Activity.eti file defines the Activity data model entity. Note that this file is part of the data model and
not a part of Cloud API.
• The schema file defines two resources that can be used by Cloud API to interact with Activity data model
objects:
1. The Activity resource, for capturing information about a single resource.
2. The Activities resource, for capturing information about a collection of resources.
• The mapping file defines how data is mapped from the Activity data model entity to the Activity resource.
• The updater file defines how data is mapped from the Activity resource to the Activity data model entity.
• The swagger file defines the CRUD operations for the endpoint. It associates an endpoint (such as /common/v1/
activities/{activityId}) to its root resource (the Activity resource).
• The apiconfig file defines the default sort order for the Activities collection resource.
All of the schema files conform to the Swagger 2 specification. For syntax details, refer to https://swagger.io/
specification/v2/.
The schema, mapping, and updater files are in JSON format using JSON Schema syntax. For details on JSON
Schema syntax, refer to http://json-schema.org/.
Reasons to modify resource definition files

Generating endpoints for custom entities
The REST endpoint generator is a tool that generates CRUD endpoints for custom data model entities. The REST
endpoint generator also creates schema definition files for the resources used by the generated endpoints. However,
these files are incomplete. Developers must always execute additional configuration in the resource definition files.
For more information on the REST endpoint generator, see “The REST endpoint generator” on page 353.
Extending base configuration resources

Cloud API has endpoints that perform CRUD operations on several data model entities in the base configuration.
For example, the GET /common/v1/activities endpoint queries for instances of the Activity data model entity.
Insurers can extend these data model entities by adding custom fields. Insurers may also want to expose these fields
to the REST endpoints. Insurers can configure schema definition files to add custom resource properties that map to
custom data model fields.
To extend a base configuration schema:
326 chapter 46: Configuring schemas
1. If necessary, extend the underlying data model entity with new fields.
a. For more information, see the Configuration Guide: Configuration Guide.
2. Configure the appropriate schema, mapping, and updater extension file.
a. For more information, see “Data mapping for new properties” on page 331
3. Add attributes to define additional property behaviors, if necessary.
a. For more information, see “Additional behaviors for properties” on page 337
Exposing base configuration fields to Cloud API
For the data model entities that are exposed in Cloud API, the base configuration does not expose every field in a
given entity to Cloud API. There may be situations where you need to expose one or more of these fields to Cloud
API.
For example, the User data model entity is exposed to Cloud API. The VacationStatus field is also exposed. But,
the ExperienceLevel field is not. An insurer may want to expose the ExperienceLevel field to Cloud API.
The approach for doing this follows the same process as extending a base configuration resource. The only
difference is that there is no need to extend the data model as the field in question already exists.
Integration graphs
Cloud API schemas are used to define the integration graphs used by Guidewire App Events . An integration graph
is a data model graph that defines a set of business information to be sent to an external application as part of
outbound integrations. For example, the Claim graph defines what information to send about a claim. Insurers may
want to extend Cloud API schemas to ensure that certain information is included in the integration graph. For more
information on integration graphs, see the App Events Guide.
Syntax for resource definition files

This section describes the syntax for the different types of resource definition files.
Schema file syntax

The file attributes
The initial part of a schema extension file contains attributes about the file itself. Do not modify these attributes, as
doing so could cause Cloud API to behave in unexpected ways.
• $schema: References the JSON Schema namespace declaration
• x-gw-combine: Lists an array of files that contain schema definitions that are either referenced by schemas in this
file or extended by schemas in this file.
The definitions section
The definitions section lists definitions for one or more schemas. For each schema, the following attributes are
specified:
• A schema title and description, which is used for API definition documentation.
• The resource type, which, for Cloud API, is typically set to object.
• A list of properties for the schema.

Every schema property includes:

• The property name (such as activityPattern in the example below)
• The property's title and description, which is used for API definition documentation.
• A "datatype" for the property.
◦ For scalar value properties, type is specified. This defines the JSON datatype of the property.
◦ For compound value properties (such as typekeys), ref is specified. This defines the URI reference for the
property.
• Optional attributes as needed for the business functionality of the property.
For example, the following is a portion of the base configuration Activity schema:
"definitions": {
"Activity": {
"title": "Activity",
"description": "An Àctivity` is an assignable item...",
"type": "object",
"properties": {
"activityPattern": {
"title": "Activity pattern",
"description": "The code of the ÀctivityPattern` used...
"type": "string"
...
},
"activityType": {
"title": "Activity type",
"description": "The type of this activity, such as `general`...",
"$ref": "#/definitions/TypeKeyReference",
...
},
...
}
}
}
Mapping file syntax

The file attributes
The initial part of a mapping extension file contains attributes about the file itself. Do not modify these attributes, as
The mapping section

A mapping file contains a mappers section, which lists one or more API resources and, for each readable property in
the resource, the way data is mapped to the property.
For each resource, the following attributes are specified:
• The schemaDefinition that defines the structure of the resource
◦ This references a schema declared in a schema.json file.
• The data model entity that serves as the root for mapping information for this resource.
• A list of properties
Every mapper property includes:
• The property name (such as closeDate, description, and mandatory in the example below)
◦ A path attribute. This is a Gosu expression that is used to populate the value of the property. Typically, this
expression returns a value from the entity defined in the root attribute.
◦ Depending on the nature of the property, there may be additional attributes.
For example, the following is a portion of the mapper for the base configuration Activity resource:
"mappers": {
"Activity": {
"schemaDefinition": "Activity",
"root": "entity.Activity",
"properties": {
"closeDate": {
"path": "Activity.CloseDate"
},
"description": {
"path": "Activity.Description"
},
"mandatory": {
"path": "Activity.Mandatory"
},
...
}
}
}
Note the following:

• This resource is defined in the schema who name is Activity (This schema is defined in some other
schema.json file.)
• The root for the resource mapping is entity.Activity.
• For each instance of the resource:
◦ The closeDate property is set to the Activity entity's CloseDate field.
◦ The description property is set to the Activity entity's Description field.
◦ The mandatory property is set to the Activity entity's Mandatory field.
Updater file syntax

The file attributes
The initial part of an updater extension file contains attributes about the file itself. Do not modify these attributes, as
The updaters section

An updater file contains an updaters section, which lists one or more API resources and, for each writeable
property in the resource, the way data is mapped to the data model.
For each resource, the following attributes are specified:
Every updater property includes:
• The property name (such as description and mandatory in the example below)
• A path attribute. This defines, for each resource property, the data model entity property into which the resource
property is to be written.
• Depending on the nature of the property, there may be additional attributes.
For example, the following is a portion of the updater for the base configuration Activity resource:
"updaters": {
"Activity": {
"properties": {

"description": {
},
"mandatory": {
},
...
}
}
}
Note the following:

• This resource is defined in the schema who name is Activity (This schema is defined in some other
schema.json file.)
◦ The value of the description property is written to the Activity entity's Description field.
◦ The value of the mandatory property is written to the Activity entity's Mandatory field.
Note that there may be properties that appear in the mapping file but not the updater file. This typically occurs with
properties that are read-only. For example, the Activity entity has a CloseDate property, which the application sets
when the activity is closed. This property appears in the mapping file, as it can be read. But it does not appear it the
updater file because it cannot be written to.
Extension files
Whenever you configure a schema, you modify an extension file. Within the context of Cloud API, an extension file
is a file that insurers can modify that adds or overrides the base configuration. All extension files have "ext" in their
name and are located in an ext subdirectory.
For schema configuration, Cloud API includes the following types of extension files:
• schema extension files, where insurers add new properties to a schema
• mapping extension files, where insurers define how data is mapped from the data model to the schema
• updater extension files, where insurers define how data is mapped from the schema to the data model (for
properties that are writeable)
Every API has its own set of extension files. The names of the files, and the nodes in Guidewire Studio that you can
use to access them, are:
• <API>_ext-1.0.schema.json
◦ integration→schemas→ext→<API>.v1
• <API>_ext-1.0.mapping.json
◦ integration→mappers→ext→<API>.v1
• <API>_ext-1.0.updater.json
◦ integration→updaters→ext→<API>.v1
Extension files have the same syntax as base configuration files. But extension files often omit some information
that is not necessary for extending a schema. For example, when a resource is declared in a base configuration file,
the schema file defines the resource's title, description, and type. When that same resource is extended in an
extension file with additional properties, there is no need to repeat the title, description, or type. These values
are inherited from the base configuration file.
Every ext subdirectory has a sibling gw subdirectory. The gw subdirectory holds the base configuration files.
Insurers are not permitted to modify these files. However, you may find it helpful to review those files for example
of how base configuration resources are defined.

Data mapping for new properties

There are different situations where you might need to add a property to a schema. This includes:
• Adding properties for custom entities that have CRUD endpoints generated by the REST endpoint generator
• Adding properties for custom fields added to a base configuration entity
Whenever you add a property to a schema, there are two or three files you must modify:
• In the schema extension file, you must add the property to the schema structure.
• In the mapping extension file, you must define how data is mapped from the data model to the schema
• In the updater extension file, you must define how data is mapped from the schema to the data model, if the
property is writeable
Every API has a set of extension files. The names of the files are:
• <API>_ext-1.0.schema.json
• <API>_ext-1.0.mapping.json
• <API>_ext-1.0.updater.json
Generally speaking, fields in a data model entity follow one of the behaviors listed in the following table. For each
behavior, there is a pattern for how the corresponding property is referenced in the schema definition files.
Field behavior Example Schema file Mapping Updater

file file
Field is not exposed to Cloud Application internal Omitted Omitted Omitted
API information, such as
<entity>.CreateUser
Field is read-only The <entity>.id field Included; declared as readOnly Included Omitted
Field must be set during Claim.LossDate Included; declared as Included Included
creation and cannot be requiredForCreate, x-gw-
changed thereafter nullable: false, and
createOnly
Field must be set during Document.Status Included; declared as Included Included

creation, but can be changed requiredForCreate, and x-gw-
later nullable: false
Field can be set or omitted Activity.Description Included Included Included

during creation, and can later
be changed
The requirements and syntax vary based on the datatype of the underlying field in the data model entity.
Naming conventions for properties

In REST APIs, the naming convention for properties is to use mixed case, with the first letter being lowercase. For
example, in the base configuration, the User entity has an ExperienceType field, which is not exposed to Cloud
API. If you were to expose this field to Cloud API, the corresponding property name would be experienceType.
If the data model entity field is an extension field on a base configuration entity, Guidewire recommends appending
an _Ext suffix to the field name. If this field is then exposed to Cloud API, Guidewire recommends retaining the
suffix in the property name. For example, suppose an insurer extended the User entity with an OnSickLeave_Ext
field. If this field were exposed to Cloud API, the corresponding property would be named onSickLeave_Ext.

The x-gw-extension object

Be aware that some property attributes are declared directly on the property itself. This includes:
• Standard JSON properties, such as readOnly
• Guidewire extension properties declared directly off the attribute, such as x-gw-sinceExtensionVersion
Other property attributes are Guidewire extensions declared in an object named x-gw-extension. This includes:
• filterable
• sortable
• requiredForCreate
When configuring properties, be sure to place each attribute in the correct place in the JSON.
Data mapping for scalars

A scalar is a single simple value, such as a string, number, datetime, or Boolean.
The schema file

In the schema file, set the type attribute to one of the JSON schema types from the following table.
Data model datatype Corresponding JSON type Additional required attributes

bit boolean
dateonly string An additional "format" attribute set to "date"

datetime string An additional "format" attribute set to "date-time"
decimal number
integer integer
longint integer
longtext string
mediumtext string
money number
percentage number
shorttext string
text string
varchar string
For example, a CustomEntityExt resource could have the following scalar properties:
"definitions": {
"CustomEntityExt": {
"title": "Custom entity ext",
"description": "Custom entity ext",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"isActive": {
"type": "boolean"
},
"customDescription": {
"type": "string"
},
"expirationDate": {
"type": "string",
"format": "date-time"

}
}
}
}
The mapping file
In the mapping file, you typically set the path attribute to a field from the data model entity. No other attributes are
required.
For example, the following maps the CustomEntityExt resource's customDescription property to the
CustomEntity_Ext data model entity's CustomDescription field.
"definitions": {
"path": "CustomEntity_Ext.CustomDescription"
}
Note:
Within the Guidewire data model, every entity has a virtual field named DisplayName. An entity name
is a Gosu expression that determines the value for an entity's DisplayName field. For example, the
ABPerson entity might have its entity name set to ABPerson.LastName+", "+ABPerson.FirstName,
which for a given ABPerson would render as "Newton, Ray". If an entity has no defined entity name,
the default behavior is to return the concatenation of every field in the entity.
If you add a property to a schema that maps to an entity's display name, be sure that there is an entity
name defined for that entity. If there is not, then the application will return a concatenation of every
field in the entity. This could potentially make information available in Cloud API that you do not
want exposed through Cloud API.
For more information on entity names, see the Configuration Guide.
The updater file
If the updater file, you typically set the path attribute to the field in the data model entity. No other attributes are
required.
For example, the following maps the CustomEntity_Ext data model entity's CustomDescription field to the
CustomEntityExt resource's customDescription property.
"definitions": {
}
Data mapping for new 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"
}

The schema file

Unlike scalar properties, compound datatype properties do not use the type attribute. They use a $ref attribute that
specifies an existing definition for the datatype. The following table lists the $ref values for the common compound
datatypes.
Compound datatype $ref value Additional required attributes

Typekey #/definitions/TypeKeyReference A x-gw-extensions attribute with a typelists child attribute that
identifies the relevant typelist.
MonetaryAmount #/definitions/MonetaryAmount
CurrencyAmount #/definitions/CurrencyAmount
SpatialPoint #/definitions/SpatialPoint
For example, the mapping for the Activity data model entity's AssignmentStatus field looks like this:
...
"typelist": "AssignmentStatus"
}
}
The mapping for the Contact data model entity's SpatialPoint field (which is a spatial point) looks like this:
"spatialPoint": {
...
"$ref": "#/definitions/SpatialPoint"
}
The mapping file

In the mapping file, you must include both the path attribute and an additional mapper attribute. The mapper
attribute specifies the mapper that defines how the compound data type is mapped into its schema. The following
table lists the mapper attribute values for the common compound datatypes.
Compound datatype mapper value

Typekey #/mappers/TypeKeyReference
MonetaryAmount #/mappers/MonetaryAmount
CurrencyAmount #/mappers/CurrencyAmount
SpatialPoint #/mappers/SpatialPoint
"path": "Activity.AssignmentStatus",
"mapper": "#/mappers/TypeKeyReference"
},
The updater file

In the updater file, if the property is writeable, you must include a valueResolver attribute with a child typeName
attribute. This attribute specifies a resolver, which defines how to map the structure for the compound datatype to
the data model entity. The updater syntax for compound datatypes is:
"<property>": {
"path": "<pathValue>",
"valueResolver": {
"typeName": "<resolverName>"

}
}
The following table lists the resolver names for the common compound datatypes.

Typekey TypeKeyValueResolver
MonetaryAmount MonetaryAmountValueResolver
CurrencyAmount CurrencyAmountValueResolver
SpatialPoint SpatialPointValueResolver
For example, the updater for the Activity resource's assignmentStatus property looks like this:
"valueResolver": {
"typeName": "TypeKeyValueResolver"
}
},
Tutorial: Data mapping for new properties

In this tutorial, you will add new properties to the base configuration User schema in the Admin API, and provide
mapping and updater information as appropriate. To reduce the number of steps required, this tutorial uses fields that
already exist on the User data model entity that are not exposed to Cloud API in the base configuration. The data
model entity fields used in this tutorial are:
• CreateTime (this datetime field will be readable but not writeable)
• Department (this string field will be readable and writeable)
• ExperienceLevel (this typekey field will be readable and writeable)
(There is an additional tutorial that covers an example of extending a base configuration entity and then extending
the base configuration resource to expose those fields. For more information, see “Tutorial: Extending a data model
entity and its API resource” on page 343.)
Tutorial steps
1. In Studio, open the admin_ext-1.0.schema.json file.
2. The file contains the following line of code.
"definitions": { }
Replace that line with the following, which defines three new properties.
"definitions": {
"User": {
"properties": {
"createDate" : {
"title": "CreateDate",
"description": "The date on which this user was created",
"type": "string",
"format": "date-time",
"readOnly": true
},
"departmentName": {
"title": "DepartmentName",
"description": "The name of the department this user works in",
"type": "string"
},
"experienceLevel": {
"title": "ExperienceLevel",

"description": "The user's level of experience (high, mid, low)",

"typelist": "UserExperienceType"
}
}
}
}
}
There is an additional readOnly property specified for createDate. For more information, see “Read-only
properties” on page 338.
At this point, you have defined the structure of the new properties. But there is no information on how data flows
into and out of this property.
3. In Studio, open the admin_ext-1.0.mapping.json file.
"mappers": { }
Replace that line with the following, which defines how data is mapped from the database to the createTime,
departmentName, and experienceLevel properties.
"mappers": {
"User": {
"properties": {
"createDate" : {
"path" : "User.CreateTime"
},
"departmentName": {
"path": "User.Department"
},
"path": "User.ExperienceLevel",
}
}
}
}
You now have three new properties with information on how data flows into each property. If these properties were
needed only for GETs (and not POSTs or PATCHes), you could restart PolicyCenter now and test your work.
5. In Studio, open the admin_ext-1.0.updater.json file.
"updaters": { }
Replace that line with the following, which defines how data is mapped from the database to the departmentName
and experienceLevel properties.
"updaters": {
"User": {
"properties": {
"departmentName": {
"path": "User.Department"
},
"path": "User.ExperienceLevel",
"valueResolver": {
}
}
}
}
}
These properties can now be used for GETs, POSTs, and PATCHes. The third property, createDate, has been
omitted from the updater file. Therefore, it is read-only and only appears in responses.
7. Start (or restart) PolicyCenter.

Testing your work

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
{
"data": {
"attributes": {
"username": "configTestUser",
"departmentName": "schema config tester",
"experienceLevel" : {
"code" : "mid"
}
}
}
}
e. Click Send.
Results
The response should be "201 Created". The response body should contain information about the new user, including
the create date, department, and experience level. Note that:
• The structure of these fields (their names and types) comes from the schema file.
• The create date, department, and experience level in the POST response comes from the mapping file.
• The setting of the user's department and experience level was accomplished by the updater file.
Additional behaviors for properties

You can configure schema properties with additional behaviors, such as:
• Setting the property to read-only
• Indicating the property is required by the database
• Making the property sortable or filterable by the corresponding collection
• Adding additional metadata, such as the first version of the API to include the property
The x-gw-extension object

Some property attributes are declared directly on the property itself. This includes:
• Standard JSON properties, such as readOnly
• Guidewire extension properties declared directly off the attribute, such as x-gw-sinceExtensionVersion
Other property attributes are Guidewire extensions declared in an object named x-gw-extension. This includes:
• filterable and sortable
• requiredForCreate
For example, if you had an expirationDate property that was filterable, sortable, and required for creation, the
syntax for the declaration of these properties would be as follows:
"properties": {
"expirationDate": {
...

"requiredForCreate": true,
"filterable": true,
"sortable": true
}
}
Read-only properties
A read-only property is a property whose value cannot be set or modified through Cloud API. This can occur for the
following reasons:
• The property is read-only in the base application.
• The property is settable in the base application, but there is a business requirement that it cannot be modified
through Cloud API.
To set a property as read-only:
1. In the schema file, set the readOnly property to true
2. In the mapping file, specify a mapper as normal.
3. Omit the property from the updater file.
For example, suppose the CustomEntity_Ext entity has an ExpirationDate field. The corresponding resource
property is read-only. The property declaration would be:
"definitions": {
...
"properties": {
...
},
"expirationDate": {
"type": "string",
"readOnly": true
}
...
The mapping declaration would be:

"mappers": {
"expirationDate": {
"path": "CustomEntity_Ext.ExprationDate"
}
There would be no updater declaration.
Properties required by the database

In the data model, some entity fields are required. You cannot create an instance of the entity without specifying a
value for the field, and the value can never be null. For example, suppose that an insurer has a business rule stating
every activity must have an end date (the date by which it is expected to be completed). To enforce this, the
Activity entity's EndDate field is required. These fields are sometimes referred to as required by the database.
In a schema, you can configure a resource property to reflect that it is required by the database. To do this, you must
set the following properties:
• "requiredForCreate": true
◦ This x-gw-extensions attribute indicates the property must be included in POST payloads.
• "x-gw-nullable": false
◦ This attribute indicates that when the property is specified, its value cannot be set to null
The "requiredForCreate": true attribute, by itself, only mandates that the property must be specified in a POST.
There is nothing to prevent a caller from including the property but setting the property's value to null.
The "x-gw-nullable": false attribute, by itself, only mandates that if the property is specified, the property's
value cannot be set to null. There is nothing to prevent a caller from omitting the property.
By combining the two expressions, you are stating that the property must be specified in a POST and set to a non-
null value, and anytime thereafter that the property is specified, it must be set to a non-null value. This is the
equivalence of setting a data model entity field to required.
For example, suppose the CustomEntity_Ext entity has an CustomDescription field, which is a string. The field is
required. The property declaration would be:
"definitions": {
...
"properties": {
...
"type": "string",
"x-gw-nullable": false,
}
}
...
Note: There is also a concept of requiredness at the schema level. You can specify a property is
required at the schema level by specifying "required": true. When a schema property is set to
required, it must be provided every time a payload is submitted. In most cases, this is not something
you would want to specify in Cloud API schemas, as it forces you to specify a value for PATCHes,
even if the property in question is not being changed.
Overriding base configuration properties

If a base configuration property is not required by the database, you can make it required by the database by adding
it to the appropriate schema extension file and setting the appropriate properties as shown in the previous example.
If a base configuration property is required by the database, you cannot make it non-required.
Properties writeable at creation only

A "writeable only at creation" property is a property whose value can only be specified in a POST and not in any
PATCH. This is used for fields that, once set, cannot be modified.
To specify a property is writeable only at creation, set the x-gw-extensions object's create-only property to true:
"create-only": true
}
For example, suppose the CustomEntity_Ext entity has an ExpirationDate field. This field can be set on a POST,
but not in any PATCH. The property declaration would be:
"definitions": {
...
"properties": {
...
"expirationDate": {
"create-only": true
}
}
}
}
}
Sortable properties
A sortable property is a property that can be optionally used to sort the elements of a collection resource.
To specify a property is sortable, set the x-gw-extensions object's sortable property to true:
"sortable": true
}

For example, suppose the CustomEntity_Ext entity has an ExpirationDate field. When retrieving a collection of
CustomEntity_Ext instances, the caller application can opt to sort the collection based on the expiration date using
a call such as:
GET /common/v1/customentity-exts?sort=expirationDate
The property declaration would be:

"definitions": {
...
"properties": {
...
"expirationDate": {
"sortable": true
}
}
Overriding base configuration properties

If a base configuration property is not sortable, you can make it sortable by adding it to the appropriate schema
extension file and, in the x-gw-extensions object, specifying sortable: true as shown in the previous example.
If a base configuration property is sortable, you cannot make it unsortable.
Limitations and performance considerations

In order to make a property sortable using the sortable attribute, the property must be directly mapped to a single
data model entity field. The property cannot be mapped to any of the following:
• A Gosu expression
• A POJO or POGO property
• Some other type of complex expression
Adding new sortable columns can have performance implications, particularly if the collection to be sorted tends to
have a very large number elements. In these cases, insurers may need to add new database indexes to maintain
acceptable performance.
Additional metadata for properties

The x-gw-sinceExtensionsVersion attribute
Every property can have an x-gw-sinceExtensionsVersion attribute. This is a string value that specifies the first
version of the API that included the extension property.
For example, the following specifies that the CustomEntity_Ext entity has an ExpirationDate field that was added
in version 1.1.0.
"definitions": {
...
"properties": {
...
"expirationDate": {
"x-gw-sinceExtensionsVersion": "1.1.0"
}
...
There is also an x-gw-sinceVersion used by Guidewire to identify the first version of the API that included a base
configuration property.
Summary of property attributes

The following attributes are direct children of the property declaration:
Attribute Description Example

readOnly Boolean identifying if the property as read-only. (The "readOnly": true
default is false.)
x-gw-nullable Boolean identifying if the property can be explicitly set "x-gw-nullable": false
to null. (The default is true.) Used to set a property as
required by the database. For more information, see
“Properties required by the database” on page 338.
x-gw- String identifying the first version of the API to include "x-gw-sinceExtensionsVersion":
sinceExtensionsVersion the extension property "1.1.0"
The following attributes are declared in the x-gw-extension object:

createOnly Boolean identifying if the property can be specified only when the object "createOnly": true
is created. (The default is false.)
filterable Boolean identifying if the filter query parameter can be used on this "filterable": true
property. In other words, collections can be filtered using this property.
(The default is false.)
requiredForCreate Boolean identifying if the property must be specified when the object is "requiredForCreate":
created. (The default is false.) Used to set a property as required by the true
database. For more information, see “Properties required by the
database” on page 338.
sortable Boolean identifying if the sort query parameter can be used on this "sortable": true
property. In other words, collections can be sorted using this property.
(The default is false.)
Collection-level behaviors
Some schema behaviors impact how the collection behaves. This can include how a collection or filtered and sorted.
Sorting a collection
You can specify a property is sortable. This gives callers the ability to sort the collection based on that property. For
more information, see “Sortable properties” on page 339.
Default sorts
You can specify that a collection has a default sort order. This sort order is used when the caller does not specify a
sort of their own. This is done in the API's apiconfig extension file.
Every API has an apiconfig extension file named <api_collection>_ext-1.0.schema.json. This file maps both
element resource and collection resources to Gosu impl files. It can also define default sort orders for collections.
For example, the following code specifies that, by default, CustomEntitiesExt collections are sorted by
expirationDate (ascending). If any elements have the same value, they are sorted by customDescription
(ascending).
CustomEntitiesExt:
defaultSort:
- expirationDate
- customDescription
To specify a descending order, use the following syntax:

- "-<propertyName>"

For example, the following code specifies that, by default, CustomEntitiesExt collections are sorted by
expirationDate (descending). If any elements have the same value, they are sorted by customDescription
(ascending).
CustomEntitiesExt:
defaultSort:
- "-expirationDate"
- customDescription
Filtering a collection
You can specify a property is filterable. This gives callers the ability to filter the collection based on that property.
For more information, see .
Swagger files
Within the context of Cloud API, a swagger file defines the endpoints and operations for a given API. Typically,
there is no need for an insurers to configure a Cloud API swagger file.
Swagger files are stored in the /apis subdirectory.
Swagger file syntax

A swagger file can contain a section that defines an API. For example, the following is a portion of the
common_pl-1.0.swagger.yaml file, which defines the Common API.
swagger: "2.0"
info:
title: "Common API"
description: "APIs for common InsuranceSuite platform objects like activities and notes"
version: "1.4.0"
basePath: /common/v1
consumes:
- application/json
produces:
- application/json
A swagger file can also contain a paths section, which defines a set of endpoint paths and the associated operations
and resources for that path. For example, the following is a portion of the common_pl-1.0.swagger.yaml file,
which defines the first path in the Common API, /activities.
paths:
/activities:
get:
summary: "Retrieve the Àctivity` elements that are assigned to the caller"
description: "Retrieves the Àctivity` elements that are assigned to the caller"
operationId: getActivities
x-gw-extensions:
childResourceType: Activity
operationType: get-collection
resourceType: Activities
x-gw-parameter-sets:
- get-collection
responses:
"200":
description: "The paginated list of Àctivity` elements"
schema:
$ref: "#/definitions/ActivityList"
Apiconfig files
Within the context of Cloud API, an apiconfig file is a glue file that maps both resources to Gosu files. The
apiconfig file is also where default sort orders for collections are defined.
The only time you need to configure an apiconfig file to connect resources to Gosu files is when you are completing
a configuration for CRUD endpoints created by the REST endpoint generator. For more information, see
“Configuring glue and impl classes for generated endpoints” on page 353.
For more information on defining default sort orders, see “Sorting a collection” on page 341.
Tutorial: Extending a data model entity and its API resource

In this tutorial, you will extend a base configuration data model entity with additional fields. You will then configure
the corresponding API resource with a set of associated properties, one for each extension field. The data model
extensions are done through Guidewire Studio. This tutorial assumes that you are familiar with working in Studio.
Scenario
You have been asked to create a resource extension for the Activity resource in the Common API. That resource is
based on the PolicyCenter Activity entity. You are going to extend resource properties to support the following
entity fields:
Entity field name Resource property name Value type Support POST
and PATCH?
ActivityClass activityClass_Ext typekey to ActivityClass typelist
CreateTime createTime_Ext datetime
CreateUser createUser_Ext foreign key to User entity
ShortSubject shortSubject_Ext varchar (10) yes
IsAutogenerated_Ext (user-created field isAutogenerated_Ext bit yes
extension)
Notice that the last entry is a custom entity field extension. You will begin by creating that field in Studio. You will
then configure the resource, mapping, and updater extensions to make these properties available through the system
API. Lastly, you will verify the resource extension in Swagger UI and Postman.
Create an entity field extension

In order to make a custom entity extension accessible through a system API, that extension first. You can create a
custom entity extension by doing the following:
1. In Studio, open the Activity entity for editing. You can find that file at Project > configuration > config
> Extensions > Entity > Activity.etx.
2. Click +, and then select column.
3. In the new column, enter the following name and value pairs:
4. In the name field, enter IsAutogenerated_Ext
5. In the type field, enter bit
6. In the nullok field, enter true
7. Save the file.
8. To integrate your changes, start the development server in debug mode by selecing Run > Debug ‘Server’.
9. To verify your work, regenerate the Data Dictionary for PolicyCenter, and then confirm the presence of this
extension in the dictionary.
Extend the schema

1. In Studio, open the schema extension file associated with the Common API.
This file is located at Integration > schemas > ext > common > v1 > common_ext-1.0.schema.json.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"x-gw-combine": [
"gw.content.pc.common.v1.common_content-1.0"
],
"definitions": {}
}
2. In the definitions field, create a schema definition extension for Activity, and add to this a properties
attribute.
{
. . .
"definitions": {
"Activity": {
"properties": {}
}
}
}
3. Within the properties attribute, create fields for each of the resource properties to be extended, as outlined in
the “Scenario” section previously.
{
. . .
"definitions": {
"Activity": {
"properties": {
"activityClass_Ext": {},
"createTime_Ext": {},
"createUser_Ext": {},
"shortSubject_Ext": {},
"isAutogenerated_Ext": {}
}
}
}
}
4. Within the activityClass_Ext property field, add a property value type for typekey.
The typekey type is defined in the schema by a URI reference. To set the property value type, enter a $ref
attribute and assign it a value of #/definitions/TypeKeyReference.
Additionally, the typekey must be associated with a typelist. To set the typelist, add a x-gw-extensions
attribute to the property, and then assign the appropriate typelist to the typelist field. In this example, the
typelist is ActivityClass.
The following code block depicts the completed property field:
{
. . .
"definitions": {
"Activity": {
"properties": {
"activityClass_Ext": {
"typelist": "ActivityClass"
}
},
. . . }
}
}
}
5. In the createTime_Ext property field, add a property value type for datetime.
To set the property value type, enter a type attribute and assign it a value of string. Next, add a format attribute
and assign it a value of date-time.
{
. . .

"definitions": {
"Activity": {
"properties": {
. . .
"createTime_Ext": {
"type": "string",
},
. . . }
}
}
}
6. In the createUser_Ext property field, add a property value type for object.
You can declare a property value type for an object by adding a $ref attribute to the resource property and
assigning it a URI reference for an inlined resource (for details, refer to “The attributes section” in this guide).
In this instance, enter a $ref attribute and assign it a value of #/definitions/SimpleReference.
{
. . .
"definitions": {
"Activity": {
"properties": {
. . .
"createUser_Ext": {
"$ref": "#/definitions/SimpleReference"
},
. . .
}
}
}
}
7. In the shortSubject_Ext property field, add a property value type for string.
To set the property value type, enter a type attribute and assign it a value of string.
{
. . .
"definitions": {
"Activity": {
"properties": {
. . .
"shortSubject_Ext": {
"type": "string"
},
. . .
}
}
}
}
8. In the isAutogenerated_Ext property field, add a property value type for bit.
To set the property value type, enter a type attribute and assign it a value of boolean.
{
. . .
"definitions": {
"Activity": {
"properties": {
. . .
"isAutogenerated_Ext": {
"type": "boolean"
}
}
}
}
}
9. Save your changes.

Extend the mapper

1. In Studio, open the mapper extension file associated with the Common API.
This file is located at Integration > mappings > ext > common > v1 >
common_ext-1.0.mapping.json.
The base file appears as follows:
{
"schemaName": "ext.common.v1.common_ext-1.0",
"combine": [
],
"mappers": {}
}
2. In the mappers field, create a mapper extension for Activity.

{
. . .
"mappers": {
"Activity": {}
}
}
3. In the Activity mapper extension, add a schemaDefinition property and give it the value Activity. This
associates the mapper with the Activity resource.
{
. . .
"mappers": {
"Activity": {
"schemaDefinition": "Activity"
}
}
}
4. Add a root property, and give it the value of entity.Activity. This associates the Activity resource with
the PolicyCenter Activity entity.
{
. . .
"mappers": {
"Activity": {
"root": "entity.Activity"
}
}
}
5. Add a properties property, and within that create fields for each of the properties that you added previously
to the schema definition extension.
{
. . .
"mappers": {
"Activity": {
"properties": {
"activityClass_Ext": {},
"createTime_Ext": {},
"createUser_Ext": {},
}
}
}
}
6. Configure the activityClass_Ext property.

a. Add a path attribute and assign it the value Activity.ActivityClass.
This maps the resource property to the ActivityClass entity field.
b. Add a mapper attribute and assign it the value #/mappers/TypeKeyReference.

Any property whose type is declared by a URI reference must have a mapping set to a URI reference for
the related mappers schema.
{
. . .
"mappers": {
"Activity": {
"properties": {
"path": "Activity.ActivityClass",
},
. . .
}
}
}
}
7. In the createTime_Ext property, add a path attribute and assign it the value Activity.CreateTime.
This maps the resource property to the CreateTime entity field.
{
. . .
"mappers": {
"Activity": {
"properties": {
. . .
"createTime_Ext": {
"path": "Activity.CreateTime"
},
. . .
}
}
}
}
8. Configure the createUser_Ext property.

a. Add a path attribute and assign it the value Activity.CreateUser.
This maps the resource property to the CreateUser entity field.
b. Add a mapper attribute and assign it the value #/mappers/SimpleReference.
Any property whose type is declared by a URI reference must have a mapping set to a URI reference for
the related mappers schema.
{
. . .
"mappers": {
"Activity": {
"properties": {
. . .
"createUser_Ext": {
"path": "Activity.CreateUser",
"mapper": "#/mappers/SimpleReference"
},
. . .
}
}
}
}
9. In the shortSubject_Ext property, add a path attribute and assign it the value Activity.ShortSubject.
This maps the resource property to the ShortSubject entity field.

{
. . .
"mappers": {
"Activity": {
"properties": {
. . .
"path": "Activity.ShortSubject"
},
. . .
}
}
}
}
10. In the isAutogenerated_Ext property, add a path attribute and assign it the value
Activity.IsAutogenerated_Ext.
This maps the resource property to the IsAutogenerated_Ext entity field.
{
. . .
"mappers": {
"Activity": {
"properties": {
. . .
"path": "Activity.IsAutogenerated_Ext"
}
}
}
}
}
Extend the updater

For the updater, you only need to add resource properties that can be updated by a POST or PATCH operation. If a
resource extension does not have any such properties, then it is not necessary to create an updater extension.
To create an updater that supports POST or PATCH operations for the isAutogenerated_Ext properties, follow
these steps.
1. In Studio, open the updater extension file associated with the Common API.
This file is located at Integration > updaters > ext > common > v1 >
common_ext-1.0.updater.json.
The base file appears as follows:
{
"schemaName": "ext.common.v1.common_ext-1.0",
"combine": [
],
"updaters": {}
}
2. In the updaters field, create an updater extension for Activity.

{
. . .
"updaters": {
"Activity": {}
}
}

3. In the Activity updater extension, add a schemaDefinition property and give it the value Activity.
This associates the updater with the Activity resource.
{
. . .
"updaters": {
"Activity": {
"schemaDefinition": "Activity"
}
}
}
4. Add a root property, and give it the value of entity.Activity.

This associates the Activity resource with the PolicyCenter Activity entity.
{
. . .
"updaters": {
"Activity": {
"root": "entity.Activity"
}
}
}
5. Add a properties property, and within that create a field for each of the supported properties as defined in
the schema definition extension.
{
. . .
"updaters": {
"Activity": {
"properties": {
}
}
}
}
6. In the isAutogenerated_Ext property, add a path attribute and assign it the value
Activity.IsAutogenerated_Ext.
This maps the resource property to the IsAutogenerated_Ext entity field, enabling property data to be
written to the InsuranceSuite database.
{
. . .
"updaters": {
"Activity": {
"properties": {
"path": "Activity.IsAutogenerated_Ext"
},
. . .
}
}
}
}
7. In the shortSubject_Ext property, add a path attribute and assign it the value Activity.ShortSubject.
This maps the resource property to the ShortSubject entity field, enabling property data to be written to the
InsuranceSuite database.
{
. . .

"updaters": {
"Activity": {
"properties": {
. . .
"path": "Activity.ShortSubject"
}
}
}
}
}
Verify the extended resource

After creating the schema definition extension, you can review the revised schema definition in Swagger UI.
1. Launch Swagger UI, and then load the Common API.
2. Select the GET /common/v1/activities/{activityId} endpoint.
3. Under Responses, select the Model view.
4. In the Activity schema associated with the data.attributes section, verify the presence of the extended
properties.
Additionally, you can test drive the revised schema definition using Postman and some sample data. This tutorial
assumes you have set up your environment with Postman and the correct sample data set. For more information, see
the Cloud API Business Flows and Configuration Guide.
First, you can review the response object of a GET operation for the resource property extensions.
3. Enter the following call, and then click Send:
GET http://localhost:8180/pc/rest/common/v1/activites/pc:105
4. Review the body of the response. It appears as follows:
{
"data": {
"attributes": {
"code": "task",
"name": "Task"
},
"activityPattern": "premium_report_overdue",
"activityType": {
"code": "general",
"name": "General"
},
"assignedByUser": {
"displayName": "System User",
"id": "systemTables:2"
},
"assignedGroup": {
"id": "pc:7"
},
"assignedUser": {
"id": "pc:105"
},
"code": "assigned",
"name": "Assigned"
},
"createTime_Ext": "2020-04-23T15:28:26.677Z",
"createUser_Ext": {
},
"description": "Premium report overdue",

"dueDate": "2020-04-27T15:28:26.682Z",
"escalated": true,
"escalationDate": "2020-04-27T15:28:26.682Z",
"externallyOwned": false,
"id": "pc:105",
"mandatory": true,
"priority": {
"code": "high",
"name": "High"
},
"recurring": false,
"status": {
"code": "open",
"name": "Open"
},
"subject": "Premium report overdue"
},
. . .
}
}
You can test the updater by executing a PATCH operation on the same resource:
3. Enter the following call, but do not click Send:
PATCH http://localhost:8180/pc/rest/common/v1/activites/pc:105
d. Paste the following into the text field underneath the radio buttons:
{
"data": {
"attributes": {
"isAutogenerated_Ext": true,
"shortSubject_Ext": "shortsub"
}
}
}
{
"data": {
"attributes": {
"code": "task",
"name": "Task"
},
"activityPattern": "premium_report_overdue",
"activityType": {
"code": "general",
"name": "General"
},
"assignedByUser": {
},
"assignedGroup": {
"id": "pc:7"
},
"assignedUser": {
"id": "pc:105"
},
"code": "assigned",
"name": "Assigned"
},
"createTime_Ext": "2020-04-23T15:28:26.677Z",

"createUser_Ext": {
},
"description": "Premium report overdue",
"dueDate": "2020-04-27T15:28:26.682Z",
"escalated": true,
"escalationDate": "2020-04-27T15:28:26.682Z",
"externallyOwned": false,
"id": "pc:105",
"isAutogenerated_Ext": true,
"mandatory": true,
"priority": {
"code": "high",
"name": "High"
},
"recurring": false,
"shortSubject_Ext": "shortsub",
"status": {
"code": "open",
"name": "Open"
},
"subject": "Premium report overdue"
},
. . .
}
}

chapter 47
Obfuscating Personally Identifiable

Information (PII)
Generally, enterprises that handle personal data must abide by the data protection and privacy regulations of the
jurisdictions in which they operate. For example, companies operating in the European Union must abide by the
General Data Protection Regulation (GDPR) within that jurisdiction.
One way to protect the privacy of individuals is to obfuscate Personally Identifiable Information (PII). This
approach limits the exposure of designated PII, and is supported by the system APIs. PII can be obfuscated by either
nullifying or masking. PII is nullified when its value is returned null. PII is masked when a portion of its value is
returned with placeholder characters, such as 'XXXXXXX-3213' as a return value for an account number.
Nullifying PII
You can nullify the return value of PII by modifying the mapper for the relevant resource property. This can be done
in a resource extension. For more information on general schema configuration, see “Configuring schemas” on
page 325.
For example, an account has AccountContacts. Depending on business purposes, it might have been necessary to
obtain tax identification information for an AccountContact. Later, a system API caller could request the
AccountContact and then view the contact's tax ID in the response. To prevent the exposure of this data, you can
nullify the value in the resource mapper.
The schema for the AccountContact resource contains a taxId property:
"AccountContact": {
"type": "object",
"discriminatorProperty": "contactSubtype"
},
"properties": {
. . .
"taxId": {
"type": "string"
},
. . .
}
}
To nullify the value of the taxId property, you can modify that property in the AccountContact mapper as follows:
"AccountContact": {
"schemaDefinition": "AccountContact",
"root": "entity.AccountContact",
Obfuscating Personally Identifiable Information (PII) 353

"properties": {
. . .
"taxId": {
"path": "null as String",
"predicate": "false"
},
. . .
}
}
Setting the taxId.path property to "null as String" converts the expected value to a null string. Setting
taxId.predicate to false prevents the original value, in this case the PII, from being evaluated.
Masking PII
You can mask the return value of PII by writing a Gosu method and modifying the mapper for the relevant resource
property to use that method. For details on implementing Gosu code, see the Configuration Guide. The mapper can
be modified through a resource extension. For more information on general schema configuration, see “Configuring
schemas” on page 325.
For example, an account has AccountContacts. Depending on business purposes, it might have been necessary to
obtain tax identification information for an AccountContact. Later, a system API caller could request the
AccountContact and then view the contact's tax ID in the response. To limit the exposure of this data, you can mask
that value.
The schema for the AccountContact resource contains a taxId property:
"AccountContact": {
"type": "object",
"discriminatorProperty": "contactSubtype"
},
"properties": {
. . .
"taxId": {
"type": "string"
},
. . .
}
}
This property is mapped to the TaxID field of the AccountContact.Contact entity. You must create a Gosu method
that masks the tax ID string. In this example, the method is named maskTaxId.
You then modify the taxId property in the AccountContact mapper as follows:
"Contact": {
"schemaDefinition": "Contact",
"root": "entity.Contact",
"properties": {
. . .
"taxId": {
"path": "AccountContact.Contact.maskTaxId(AccountContact.Contact.TaxID)"
},
. . .
}
}
With the taxId.path property set to AccountContact.Contact.maskTaxId(AccountContact.Contact.TaxID) ,

the value of TaxID is passed through the maskTaxId method before being exposed to the caller.
Changing the masking pattern

To change the masking pattern applied to a resource property, you can either revise the existing masking Gosu
method or write a new one.
Unmasking PII
Conversely, you can unmask PII that has been masked in the base configuration. This can be necessary when you
need to expose the PII to a specific internal role, such as administrator. In such circumstances, Guidewire
354 chapter 47: Obfuscating Personally Identifiable Information (PII)
recommends that you create a new schema extension for the masked property. For example, if you wish to unmask
the taxId property, you would create a taxIdUnmasked_Ext schema property that is mapped directly to the TaxID
entity field. In such a case, Guidewire recommends that you also allowlist the extended property to make it visible
only to authorized roles. For details on creating resource extensions, see “Configuring schemas” on page 325. For
details on allowlisting fields, see the section on API role files in Cloud API Authentication Guide.
IMPORTANT Nothing in the Cloud API infrastructure prevents configuration that could expose PII in
a sensitive way. For example, if you specify taxId as a filterable parameter or sortable, it can be
included as part of the URL in a request and is more likely to appear in application logs.
Obfuscating Personally Identifiable Information (PII) 355

356 chapter 47: Obfuscating Personally Identifiable Information (PII)

chapter 48
Localizing schemas
Schema definition files define the behavior of REST APIs and their endpoints. They also provide API definition
documentation. This is information in an API definition file to help users better understand API functionality.
For example, one of the schemas defined in the common_pl-1.0.schema.json file is the Activity schema. The
definition includes this description property:
"description": "An Àctivity` is an assignable item that represents a task to be done, a
decision to be made, or information to be aware of"
API definition documentation is included in the responses when using the /openapi.json and /swagger.json
endpoints in Cloud API. Users can view this information directly, through API definition tools such as Swagger UI,
or in other contexts such as contextual help in a rules editor. Different users working with the same REST APIs
could be working in different languages. Therefore, the Guidewire REST API Framework (and Cloud API, which
rests on top of that framework) supports the ability to localize schema definition documentation. This capability is
loosely referred to as "schema localization".
This topic discusses how to add locale-specific text to schema definition documentation.
Architecture of localized text

API definition documentation that has been localized is defined in a set of "schema.display.properties" files.
Location of schema.display.properties files

For a given InsuranceSuite application, the "schema.display.properties" files are stored in the /modules/
configuration/config/locale directory.
• There is one default file named schema.display.properties.
◦ This file contains schema information in English.
• There is one schema.display_LOCALE.properties file for each locale. Each file contains schema information
for that locale. For example:
◦ The schema.display_fr.properties file contains schema information in French.
◦ The schema.display_es.properties file contains schema information in Spanish (for Latin American
locales).
◦ The schema.display_es_ES.properties file contains schema information in Spanish (for Spain).
In a given situation, if the locale is not English but the given display value cannot be found for the desired locale, the
value in the default schema.display.properties is used. If for some reason the value cannot be found in the
default schema.display.properties either, the text from the corresponding schema file property is used. For
Localizing schemas 357
example, if localized text for an API title cannot be found in any schema.display file, the value of the schema file's
title property is used.
The schema.display.properties files can be viewed in Studio by accessing the config→Localizations→Resource
Bundle 'schema.display' node.
Note that the base configuration does provide schema.display_LOCALE.properties files for several locales, but
these files may not be complete. Before using them in a production environment, Guidewire recommends reviewing
the contents to verify completeness and correctness of the translations.
schema.display.properties keys
Every schema localization file contains a series of key/value pairs. For example:
json.common.v1.definitions.Activity.properties.activityType.description =
The type of this activity, such as `general` or àpproval`
The key is the text that comes before the "=". It defines a piece of localizeable text in a locale-generic way. Keys for
schema information are written in the following way:
• Keys for values defined in a schema.json file start with json.
• Keys for values defined in a swagger.yaml file start with swagger.
• The remainder is a dot-notation string that follows a specific pattern to identify the corresponding schema
component, such as "common.v1.definitions.Activity.properties.activityType.description".
Each key must adhere to a specific pattern in order to be associated with the correct schema element. In most cases,
the pattern for the key corresponds to the path to the localized property within the schema file. But there are
additional nuances to the patterns. For more information, see “Associating display keys with API elements” on
page 360.
Note: Display keys used in an InsuranceSuite user interface have key values that are arbitrary. You
can define a key any way you desire, provided that any user interface element using the key references
the same value. Display keys for API definition documentation do not behave this way. The key must
adhere to a specific pattern to be associated with the correct aspect of the API definition.
schema.display.properties values
The value is the localized text to use for that key when the user is working in the given locale. For example, suppose
the key/value pair for the description of an Address is as follows:
json.common.v1.definitions.Address.description = An Àddress` represents a postal address. The
fields available on an Àddress` will depend upon the `country` value for the Àddress`.
If a key must be shown in multiple languages, then it is defined in each locale-specific file as needed. The key
remains constant across all files. Only the value varies.
For example, the following key/value pairs come from the default schema.display.properties file:
json.common.v1.definitions.Address.properties.CEDEX.description = The CEDEX bureau of the address.
Only applicable in certain countries.
The following key/value pairs come from the base configuration schema.display_fr.properties file:
json.common.v1.definitions.Address.properties.CEDEX.description = Bureau CEDEX de l'adresse.
Applicable uniquement dans certains pays.
Determining which value to use

Cloud API returns API definition documentation through:
• The /openapi.json and /swagger.json endpoints in each API.
• The schemas returned by the Cloud API-specific /job/v1/graph-schema and /claim/v1/graph-schema
endpoints.
When calling these endpoints, the request object can include a GW-Language header set to a given language, such as
"fr_FR". For more information on this header, see “Globalization” on page 119.
358 chapter 48: Localizing schemas
When the GW-Language header is present, Cloud API attempts to return API definition documentation in the
request language. For each piece of documentation, a localized value is returned if all of the following are true:
• There is a schema.display.properties file for that language.
• The schema.display.properties file defines a value for the corresponding key.
In all other circumstances, a default value is used. The value defined in the default schema.display.properties
file is used, if it exists. If it does not exist, the corresponding value from the schema definition file itself is used.
For example, suppose an InsuranceSuite application has an Address schema that includes properties for
addressLine1, arrondissement, and CEDEX. The following information exists in each of the following files:
The schema definition file
"Address": {
...
"properties": {
"addressLine1": {
"description": "The first line of the address",
"type": "string",
},
"arrondissement_Ext": {
"description": "The administrative district of the address. Used in certain large
French cities, in particular Paris.",
"type": "string",
},
"CEDEX": {
"description": "The CEDEX bureau of the address. Only applicable in certain countries.",
"type": "string",
}
The schema.display.properties file

json.common.v1.definitions.Address.properties.addressLine1.description = The first line of the
address, such as "123 Main Street"
json.common.v1.definitions.Address.properties.CEDEX.description = The CEDEX bureau of the
address. Only applicable in certain countries.
The schema.display_fr.properties file:

json.common.v1.definitions.Address.properties.CEDEX.description = Bureau CEDEX de l'adresse.
Applicable uniquement dans certains pays.
Now, suppose a caller requests schema information in French for the following keys:
• json.common.v1.definitions.Address.properties.CEDEX.description
• json.common.v1.definitions.Address.properties.Address.description
• json.common.v1.definitions.Address.properties.Arrondissement_Ext.description
Cloud API returns the following values:
• First key
◦ Return value: "Bureau CEDEX de l'adresse. Applicable uniquement dans certains pays."
◦ Reason: There is a schema,display.properties file for French and the file defines this key.
• Second key
◦ Return value: "The first line of the address, such as "123 Main Street"
◦ Reason: Even though there is a schema,display.properties file for French, the file does not define this key.
However, the key is defined in the default schema,display.properties file.
• Third key
◦ Return value: "The administrative district of the address. Used in certain large French cities, in particular
Paris."
◦ Reason: The key is not defined in either the locale-specific schema,display.properties file or the default
schema,display.properties file. Therefore, the value of the description property in the schema definition is
returned.

Associating display keys with API elements

Every API is defined in multiple files. For a given API:
• There are one or more schema.json files that define the schemas.
• There are one or more swagger.yaml files that define endpoints and their behaviors.
In order to pair localized keys with the correct API elements:
• Every schema.json file and swagger.yaml file must provide or inherit a localization key prefix.
◦ The prefix can be declared added to a file.
◦ The prefix can be inherited from another file when schemas are combined. For example, the schema extension
files, such as account_ext-1.0.swagger.yaml, are combined with base configuration files. Localization
prefixes declared in the base configuration files are inherited by the schemas in the extension files.
• Every display key must adhere to a specific pattern that uses the localization key prefix.
Localization key prefixes

If a schema.json file or swagger.yaml file contains API definition documentation that must be localized, the file
must include an x-gw-localizationKeyPrefix property. This property defines a prefix used to map display keys to
properties in that file.
Syntax
In the base configuration, the convention for the localization key prefix is to name it <APIname>.<majorVersion>.
For example: common.v1.
To add a localization key prefix to a schema.json file, use:
"x-gw-localizationKeyPrefix": "<localizationKeyPrefix>"
For example, in the base configuration, the common_pl-1.0.schema.json files includes the following:
"x-gw-localizationKeyPrefix": "common.v1"
To add a localization key prefix to a swagger.yaml file, use:

x-gw-localizationKeyPrefix: <localizationKeyPrefix>
For example, in the base configuration, the common_pl-1.0.swagger.yaml files includes the following:
x-gw-localizationKeyPrefix: common.v1
Display key patterns for schema.json-files

schema.json files have two basic types of documentation text: titles and descriptions. They can be declared at four
levels:
• The API itself
• API resources
• API resource properties
• The API resource additionalProperties property
Title and description for the schema

The following display keys map to the title and description of a schema:
• json.<localizationPrefix>.title
• json.<localizationPrefix>.description
There are no examples of this in the base configuration.
Titles and descriptions for schema definitions

The following display keys map to the title and description of each schema definition:
• json.<localizationPrefix>.definitions.<definitionName>.title
• json.<localizationPrefix>.definitions.<definitionName>.description
For example, the description property for the Common API's Activity schema definition (declared in
common_pl-1.0.schema.json) maps to json.common.v1.definitions.Activity.description.
Titles and descriptions for schema definition properties

The following display keys map to the title and description of each property on a given schema definition:
• json.<localizationPrefix>.definitions.<definitionName>.properties.<propertyName>.title
• json.<localizationPrefix>.definitions.<definitionName>.properties.<propertyName>.descriptio
n
For example, the description property for the Common API's Activity schema definition's activityType property
(declared in common_pl-1.0.schema.json) maps to
json.common.v1.definitions.Activity.properties.activityType.description.
Titles and descriptions for a schema definition "additionalProperties" property

The following display keys map to the title and description of the additionalProperties property on a given
schema definition:
• json.<localizationPrefix>.definitions.<definitionName>.additionalProperties.<propertyName>.
title
• json.<localizationPrefix>.definitions.<definitionName>.additionalProperties.<propertyName>.
description
For example, the description property for the Composite API's Headers schema definition's additionalProperties
(declared in composite_pl-1.0.schema.json) maps to
json.composite.v1.definitions.Headers.additionalProperties.description.
Summary of title and description mappings
Level Property Display key pattern Exampl

Schema title json.<localizationPrefix>.title json.c
Schema description json.<localizationPrefix>.description json.c
Schema definition title json.<localizationPrefix>.definitions.<definitionName>.title json.c
Schema definition description json.<localizationPrefix>.definitions.<definitionName>.description json.c
Schema definition title json.<localizationPrefix>.definitions.<definitionName>.properties.<propertyName>.title json.c

property
Schema definition description json.<localizationPrefix>.definitions.<definitionName>.properties.<propertyName>.description json.c
property
Schema definition title json.<localizationPrefix>.definitions.<definitionName>.additionalProperties.title json.c
additionalProperty
Schema definition description json.<localizationPrefix>.definitions.<definitionName>.additionalProperties.description json.c
additionalProperty
Display key patterns for swagger.yaml files

Schema definitions and their properties (except for the top-level title and description properties) can be defined in
swagger.yaml files. Therefore, the key patterns that can be used in schema.json files can also be used in
swagger.yaml files. The one difference is that the display key patterns start with schema.<localizationPrefix>,
rather than json.<localizationPrefix>. For a list of these key patterns, refer to the previous topic.
swagger.yaml files also support an additional set of documentation text. The following table lists the different types
of text and the patterns for the display keys. Note that the base configuration makes use of some of these patterns,
but not all of them.
Display key pattern Example Notes

info.title swagger.<localizationPrefix>.
swagger.claim.v1.info.title
info.description swagger.<localizationPrefix>.
swagger.claim.v1.info.description
info.termsOfService swagger.<localizationPrefix>.
swagger.claim.v1.info.termsOfService
info.license.name swagger.<localizationPrefix>.
swagger.claim.v1.info.license.name
tags.<name>.description swagger.<localizationPrefix>. "name" refers to the "name" property of the tag
swagger.claim.v1.tags.claim.description itself
tags.<name>. swagger.<localizationPrefix>.
externalDocs.description swagger.claim.v1.tags.claim.
externalDocs.description
securityDefinitions.<RefName>. swagger.<localizationPrefix>. "RefName" refers to the name the top-level security
description swagger.claim.v1.securityDefinitions. definition is referenced by
oauth.description
parameters.<RefName>. swagger.<localizationPrefix>. "RefName" refers to the name the top-level
description swagger.claim.v1.parameters.claimId. parameter is referenced by, not to the "name"
description property of the parameter
parameterSets.<RefName>. swagger.<localizationPrefix>. "RefName" refers to the name of the parameter set,

<in>.<name>.description swagger.claim.v1.parameterSets. "in" and "name" refer to the respective values of
standardParameters. the parameter within the set
query.prettyPrint.description
responses.<RefName>. swagger.<localizationPrefix>. "RefName" refers to the name the top-level
description swagger.claim.v1.responses. response is referenced by
standard200.description
responses.<RefName>. swagger.<localizationPrefix>. "RefName" refers to the name the top-level
headers.<HeaderName>. swagger.claim.v1.responses. response is referenced by
description standard200.headers.
GW-Checksum.description
externalDocs.description swagger.<localizationPrefix>.
swagger.claim.v1.
externalDocs.description
operations.<operationId>. swagger.<localizationPrefix>.
summary swagger.claim.v1.operations.
getClaim.summary
description swagger.claim.v1.operations.
getClaim.description

Display key pattern Example Notes

externalDocs.description swagger.claim.v1.operations.
getClaim.externalDocs.description
operations.<operationId>. swagger.<localizationPrefix>. Note that parameter names are not unique, only
parameters.<in>.<name>. swagger.claim.v1.operations. the combination of "in" and "name" is unique, so
description getClaim.parameters.query. the property path for operation-level parameters
must include both pieces
customParam.description
responses.<Code>.description swagger.claim.v1.operations.
getClaim.responses.
200.description
responses.<Code>.headers. swagger.claim.v1.operations.
<HeaderName>.description getClaim.responses.200.headers.
GW-Checksum.description
paths.<Path>.parameters. swagger.<localizationPrefix>.
<in>.<name>.description swagger.claim.v1.paths.claims.
_claimId_.parameters.path.
claimId.description
Providing locale specific content for a given locale

Adding localized text for existing API elements
The base configuration provides several schema.display_LOCALE.properties files, but these files are incomplete.
You can complete these files by adding localized text for existing API elements.
In this case, you must do the following:
• In each schema.display_LOCALE.properties file, add the necessary key/value pairs.
1. The keys must match the required pattern to identify the appropriate API element.
2. The value must be the localized text.
Adding localized text for new API elements

You can add localized text for new API elements for a locale that is already present in the base configuration. This
could be required in the following situations:
• You extend a base configuration resource to include additional fields.
• You generate new endpoints using the REST endpoint Generator.
1. In the relevant schema.json files, add the localization key prefix.
2. In the relevant swagger.yaml files, add the localization key prefix.
3. In each schema.display_LOCALE.properties file, add the necessary key/value pairs.
a. The keys must match the required pattern to identify the appropriate API element.
b. The value must be the localized text.
Adding a new locale

You can add localized text for a new locale. This could be required when you need to support a locale that is not
present in the base configuration.

1. Create a new schema.display_LOCALE.properties file in the /modules/configuration/config/locale
directory.
2. In this file, add the necessary key/value pairs.
a. The keys must match the required pattern to identify the appropriate API element.
b. The value must be the localized text.
Note that each InsuranceSuite instance can have only one schema.display.properties file for a given locale.

chapter 49
APIs for lines of business
Every product in PolicyCenter consists of one or more lines of business (LOBs). From a technical standpoint, every
line of business is implemented through a set of LOB-specific artifacts. This can include the following:
• Database tables that store LOB-specific information
• LOB-specific PCFs
• LOB-specific reference tables, such as tables that store class codes
When a line of business is exposed to the system APIs, there is an additional set of LOB-specific artifacts: the LOB-
specific APIs. An LOB-specific API is a set of endpoints that can create, read, update, or delete information for a
specific line of business. Every LOB-specific API includes endpoints to work with Line resources. Depending on
the structure of the line of business, the API may include other endpoints, such as:
• Endpoints to work with coverables
• Endpoints to work with locations
Every insurer develops lines of business for their specific needs. This can involve modifying base configuration
LOBs or creating new ones. Because of this, the base configuration does not include any LOB-specific APIs.
Insurers must generate the APIs for themselves after the structure of the line of business has been sufficiently
developed. PolicyCenter provides functionality that lets you generate APIs for the LOBs that support API
generation.
Note:
Line of business configuration can vary depending on the LOB. For further assistance, contact
Guidewire Support.
Generating and installing LOB-specific APIs

The following diagram provides a high-level overview for how a line of business is typically developed using
Advanced Product Designer.
APIs for lines of business 365

1. The product and its lines of business start as metadata that is captured in either a mind map or a template.
2. The insurer creates a visualized product by importing the LOB metadata into PolicyCenter.
a. During the import, PolicyCenter generates a set of "in memory" APIs that reflect the structure of the
LOB.
3. While in Advanced Product Designer, the insurer typically edits the product.
a. This is typically an iterative process where the insurer refines the metadata as needed.
b. Every time the product is modified, the "in memory" APIs are regenerated.
4. Once the refining is complete, the insurer creates a finalized product by installing the product. The finalized
products consists of:
a. The necessary artifacts for the product, including database tables and PCFs.
b. A set of "active" APIs that are now part of the system APIs.
Note: When importing, editing, or installing a line of business through Advanced Product Designer,
there is no separate step to generate LOB-specific APIs. The APIs are generated automatically
whenever the product is imported, edited, or installed.
For more information on Advanced Product Designer, refer to the Advanced Product Designer Guide.
Related developer tasks
When working with LOB-specific APIs, developers can do the following:

• Generate LOB-specific APIs as part of an entire product (through Advanced Product Designer)
• Generate a template from an existing finalized product
• Install LOB-specific APIs without modifying other product-specific artifacts
Generating LOB-specific APIs through APD

When you import, edit, or install a product through Advanced Product Designer, LOB-specific APIs are
automatically generated. For more information on how to use Advanced Product Designer, refer to the Advanced
Product Designer Guide.
Note that the generation of APIs through Advanced Product Designer can be either seamless or bootstrapped.
• If the line of business supports seamless generation, then the LOB-specific APIs are generated automatically
from the visualized product. No manual modifications are required.
• If the line of business supports only bootstrapped generation, then some manual modification of the generated
APIs is required.
366 chapter 49: APIs for lines of business

Generate LOB-specific APIs

About this task
You can generate an LOB-specific API from an APD template. This process applies to both creating new LOB-
specific APIs as well as updating existing APIs.
Note:
PolicyCenter upgrades include new features for use with the Cloud APIs. In order to apply these new
features to your LOB-specific APIs, you must update each of those APIs after upgrading PolicyCenter
itself.
To execute this task, you must have an APD template for the LOB. If necessary, you can generate an APD template
from the existing visualized product and import the template. For more information, see “Generate a template using
the reverse template generator” on page 367
Procedure
1. In PolicyCenter, set Options→Preferences→Product Design Mode to Developer, and then click Update.
2. To add the template, click Administration→Product Management→Import From Template, browse and select
your template, and then click Update.
3. To generate the API, from the Details pane click Edit Product→Generate Product Code→System APIs→System
APIs - Code
4. Review the model, and if acceptable, click Complete Generation.
5. Click Return to Product Definition, and then click Save.
6. Restart PolicyCenter.
Result
To verify the result, browse to the APD Managed pane on the Product Management page. The LOB product will be
displayed, and the Last Updated column will have a value, indicating that the product has been installed. For details
on viewing the API in Swagger, see “View an API definition using Swagger UI” on page 29.
Generating templates from a finalized product

Products can be created in PolicyCenter using approaches other than Advanced Product Designer. These approaches
create a product with several LOB-specific artifacts (such as LOB-specific database tables or PCFs). But, they do
not create any LOB-specific APIs. If you want to expose these lines of business to the system APIs, you need to
generate LOB-specific APIs.
You can achieve this by doing the following:
1. Create a template for the product using the reverse template generator.
2. Import the product into Advanced Product Designer.
3. From the imported product, install only the LOB-specific APIs.
The reverse template generator is a script that creates an XML template from an installed product. Because the
generator generates XML based on the installed product, the resulting template typically has more information in it
than what exists in a mind map or in a product that is only visualized.
Advanced Product Designer is not required to run the reverse template generator. Therefore, it is possible to run the
reverse template generator in older versions of PolicyCenter to generate a template. However, Advanced Product
Designer is required to import the template and install the corresponding APIs.
Generate a template using the reverse template generator

Procedure
1. In PolicyCenter, select Administration→Product Management→Externally Managed. This pane contains a list
of products that have been installed by means other than APD.
2. In the Installed Products pane, select the product for which you wish to generate an APD template.
3. In the Details pane, click Extract APD Representation. PolicyCenter generates the APD template and stores it in
the <USER_HOME>/Downloads directory.
Result
Once the product is imported as a visualized product and any inconsistencies have been corrected, you can install
just the APIs. For details, see “Generate LOB-specific APIs” on page 367.
Installing LOB-specific APIs without installing other artifacts

In some situations, you may have an installed product that has no LOB-specific APIs. For example, this can occur
when a product has been created outside of Advanced Product Designer, such as:
• A base configuration product
• A product installed from a Standards Based Template (SBT)
• A product created in Product Designer
You can create a template from the installed product using the reverse template generator, and then import the
template into Advanced Product Designer. Once the product has been imported, you can install only the APIs,
without modifying any of the other existing product-specific artifacts.
API codegen configuration

APD-generated products adhere to certain naming conventions and behaviors that simplify API generation.
However, when generating LOB-specific APIs from an APD template that has been exported from a non-APD
product, it is possible for naming conflicts to arise during code generation that cause build failure, since the existing
product may have irregular entity names or other functionality not yet supported by APD.
In such a circumstance, you can apply an API codegen configuration file for the non-APD product. The codegen
configuration can be used to map any mismatches of type or field names between the non-APD product with those
used in the associated APD template. Additionally, it is possible to override certain behaviors, such as constraints,
that exist in the non-APD product but are not reflected in its APD template.
Note:
API codegen configuration can become quite complex, depending on the LOB. For assistance, contact
Guidewire Support.
Applying API codegen overrides

In order to apply API codegen overrides to a legacy product, the following criteria must be met:
• The directory config→Integration→apis→installedlobs must be present in your system. If it is not present, then
you must create it.
• That directory must contain the API codegen configuration file, in YAML format.
• The file name must be in the form <xx>_codegen_config.yaml, in which <xx> is the product suffix.
After meeting the above conditions, you must regenerate the product API.
API codegen configuration syntax

Resolving mismatched type/field names
Sometimes, there can be a mismatch between APD-generated types and the fields in the corresponding product,
particularly when the template has been exported from a non-APD product. The API codegen configuration file can
be used to specify mapping information that resolve these mismatches.
The API codegen configuration file must have a top-level types property followed by one or more APD-generated
types. Each APD-generated type can specify a nameOverride property, which identifies the relevant type name in
the product. Product values are case-insensitive, but APD-generated values are case-sensitive and the case must
match. The syntax for this is as follows:
types:
<APDGeneratedName>:
nameOverride: <TypeNameInProduct>
For example, suppose you have an APD-generated type PALine, which corresponds to the product's
PersonalAutoLine. The following code maps these values.
types:
PALine:
nameOverride: PersonalAutoLine
For each type, you can also provide type-to-field mapping by specifying a fields property. The fields property
includes an array of one or more APD-generated types to override. Each type name contains a nameOverride
property that identifies the field name as used in the product. As is the case with the parent type value, APD-
generated field-level values must match the case of the APD-generated type values. The syntax for this is as follows:
types:
<APDGeneratedName>:
nameOverride: <TypeNameInProduct>
fields:
<APDGeneratedName>:
nameOverride: <FieldNameInProduct>
For example, suppose you have an APD-generated type PALine, which corresponds to the product's
PersonalAutoLine. There is also an APD-generated Year type which corresponds to the product's ModelYear field.
The following code identifies how to map these values.
types:
PALine:
fields:
Year:
nameOverride: ModelYear
Modifying field constraints

In addition to applying naming overrides, it is also possible to apply or relax type or field constraints enforced in the
APD template that differ from the behavior expected in the originating product.
The following optional properties can be used to override specific aspects of a type or field:
• autonumber: Accepts resource name of the schema and mapping to be used in lieu of the default sorting
• canDelete: Enable or disable DELETE method (Boolean)
• canPatch: Enable or disable PATCH method (Boolean)
• canPost: Enable or disable POST method (Boolean)
• canSplit: Enable or disable the split custom action (Boolean)
• createOnly: Enable or disable modifiers (Boolean)
• identifier: Override default identifying property
• ignored: Hide or expose the field (Boolean)
• nullable:: Allow a null value (Boolean)
• oneToOne: Enforce a one-to-one relationship by removing the ability to add or remove values
• requiredForCreate: Override the APD-derived requiredForCreate value (Boolean)
• resourceName: Override default schema and resource name. Apply this value when the resource name differs
from the nameOverride name.
• toCreateAndAdd: Override default createAndAdd method
• toRemove: Override default remove method
• wizardStepIds: Add or drop wizard step identifiers (Boolean)
The following code block is an example of an API codegen configuration for a Personal Auto line that includes
optional properties:
types:
PADriver:

nameOverride: VehicleDriver
fields:
PolicyDriver:
createOnly: true
PALine:
PAPolicyDriverMVR:
nameOverride: PolicyDriverMVR
# PolicyDriverMVRs are managed implicitly via requests to retrieve an MVR on individual drivers and are read-only
canDelete: false
canPatch: false
canPost: false
PAVehicle:
nameOverride: PersonalVehicle
fields:
GarageLocation:
requiredForCreate: false
Year:
nameOverride: ModelYear
autonumber: VehicleNumber
toCreateAndAdd: createAndAddVehicle
toRemove: removeVehicle
wizardStepIds: false
Disabling product artifacts during testing

Multiple sets of product artifacts
During the development of an APD product, the product moves from a visualized product to a finalized product.
However, product development does not always move in a single direction. Rather, it is typically an iterative
process. Testing of the finalized product may uncover issues that require fixes to the visualized product. Once the
visualized product has been fixed, it must be reinstalled as a finalized product and retested.
Thus, during product testing, it is not unusual to have two sets of product artifacts: one for the visualized product
and one for the finalized product. Furthermore, these two sets of product artifacts are not necessarily in sync at all
times.
Disabling product artifacts
The LOB-specific APIs use the product artifacts as the backing data source for the APIs. However, the LOB-specific
APIs can only access one set of product artifacts at a time. Because there might be multiple sets of product artifacts,
the system APIs give you the ability to disable either set of product artifacts. Disabling a set of product artifacts can
also be useful when you have inadvertently created a line with internal errors that are significant enough that it could
prevent PolicyCenter from running.
Every product has an Enable for REST API flag. When this flag is set to Disabled, the system APIs will not use the
visualized product artifacts. This field is visible in Advanced Product Designer on the Product Definition screen only
when the user's Product Design Mode preference is set to Developer.
Every installed product has a product file in the integration/apis/installedlobs directory. This is a YAML file
whose name starts with the product's Abbreviation as defined on the Product Definition screen. If this file is renamed
or removed, the system APIs will not use the finalized product artifacts.
Disabling product artifacts typically occurs in development environments only. This is because it is unlikely that a
visualized product (or a product with significant errors) would be brought into a production environment.
Determining which product artifacts to use

If there is only a visualized set of product artifacts, the system APIs will use these artifacts. (However, if the
visualized artifacts have been disabled, the system APIs will throw an error.)
If there is only a finalized set of product artifacts, the system APIs will use these artifacts. (However, if the finalized
artifacts have been disabled, the system APIs will throw an error.)
If there is both a visualized set of product artifacts and a finalized set of product artifacts, the system APIs check the
product's Enable for REST API flag.
• If the flag is set to Enabled, the visualized set is used.
• If the flag is set to Disabled (and the product file is in the installedlobs directory), the finalized set is used.
Disable a product's visualized artifacts

About this task
Disabling a visualized product is useful when you want to test the finalized product. It can also be useful when you
have inadvertently created a line with internal errors that are significant enough that it could prevent PolicyCenter
from running.
Procedure
1. Set your Product Design Mode preference to Developer. (You can do this by selecting Preferences from the
Options menu. The Options menu is represented by the gear icon in the upper right corner.)
2. Navigate to the product's Product Definition screen.
3. Set Enabled for REST API to Disabled.
Result
PolicyCenter immediately disables the product's visualized artifacts.
Enable a product's visualized artifacts

About this task
Enabling a visualized product is useful when you have previously disabled the visualized product (for example,
when testing the finalized product) and you now want to re-enable the visualized product (for example, to conduct
further testing on the visualized product).
Procedure
1. Set your Product Design Mode preference to Developer. (You can do this by selecting Preferences from the
Options menu. The Options menu is represented by the gear icon in the upper right corner.)
2. Navigate to the product's Product Definition screen.
3. Set Enabled for REST API to Enabled.
Result
PolicyCenter immediately enables the product's visualized artifacts.
Disable a product's installed artifacts

About this task
Disabling a finalized product can also be useful when you have inadvertently created a line with internal errors that
are significant enough that it could prevent PolicyCenter from running.
Procedure
1. In Windows Explorer, navigate to the integration/apis/installedlob directory.
2. Either rename or delete the product file corresponding to the installed product.
Result
PolicyCenter immediately disables the product's installed artifacts.
Managing LOB-specific APIs for testing and integration

The Product Definition API provides endpoints that can be used to import, visualize, and generate code for products
from Advanced Product Designer product templates. These APIs are designed to assist you in managing your
product testing and integration. For building product models, Guidewire recommends using Advanced Product
Designer directly.
Importing a product template through the API

The Product Definition API provides a set of endpoints that can be used to import a product from an Advanced
Product Designer (APD) product template.
Endpoint Template type Input file format

/productdefinition/v1/import-template An APD product template XML
/productdefinition/v1/import-edition An APD product template, imported as a product edition XML
/productdefinition/v1/import-xmind An XMind mind map that can be used to generate an APD XMIND
product template
/productdefinition/v1/import-json An APD product template JSON
In the request body, Content-Type must be set to multipart/form-data, and the product template file must be
passed through the content parameter.
The following example shows a partial request header for a call that imports a BPP-PetBusinessOwners-
template.xml file:
> POST /pc/rest/productdefinition/v1/import-template HTTP/1.1
> Accept-Encoding: gzip,deflate
> Authorization: Basic c3U6Z3c=
> Connection: Keep-Alive
> Content-Type: multipart/form-data; boundary=--------iSl9mNZkwq31beJX5v
> Transfer-Encoding: chunked
> --------iSl9mNZkwq31beJX5v
> Content-Type: text/xml
> Content-Disposition: form-data; content="BPP-PetBusinessOwners-template.xml"
(content of BPP-PetBusinessOwners-template.xml)
> --------iSl9mNZkwq31beJX5v--
A successful request returns the following response body:

{
"data": {
"attributes": {
"id": "Petbusinessowners"
}
}
}
By default, the imported product template is loaded in PolicyCenter as a visualized product, and its LOB-specific
APIs are enabled for inspection.
Product editions
A product edition defines product model properties and subclause relationships for a product line. Product editions
can be used to introduce changes to the product after a product has gone into production. A product edition is
packaged as an APD template, and can be imported as described above, provided the base product is already
installed.
To activate the product edition, a caller can submit a POST request to the /productdefinition/v1/lines/
{lineId}/activate-editions endpoint. The request body must contain a lineId property containing the product
edition identifier:
{
"data": {
"attributes": {
"lineId": "Petbusinessowners-2"
}
}
}
Querying for product templates

Authorized internal users can query for product templates. Authorized callers can use the following endpoints to
retrieve product template resources:
• /productdefinition/v1/product-templates
• /productdefinition/v1/product-templates/{productId}
For example, a ProductTemplate resource for a Pet Business Owners product appears as follows:
{
"data": {
"attributes": {
"abbreviation": "PBP",
"codeIdentifier": "PetBusinessOwners",
"description": "Pet Business Owners",
"enabled": true,
"id": "Petbusinessowners",
"name": "Petbusinessowners",
"productAccountType": {
"code": "Any",
"name": "Any"
}
},
. . .
"links": {
"codegen": {
"href": "/productdefinition/v1/product-templates/Petbusinessowners/codegen",
"methods": [
"post"
]
},
"disable": {
"href": "/productdefinition/v1/product-templates/Petbusinessowners/disable",
"methods": [
"post"
]
},
"self": {
"href": "/productdefinition/v1/product-templates/Petbusinessowners",
"methods": [
"delete",
"get"
]
}
}
}
}
Toggling the active state of a visualized product

By default, importing a product template creates a product in visualized mode and enables its API for queries. The
Product Definition API provides endpoints for toggling this state:
• /productdefinition/v1/product-templates/{productId}/enable
• /productdefinition/v1/product-templates/{productId}/disable
The request body for either call is the same. It contains a productId property whose value is the product identifier.
{
"data": {
"attributes": {
"productId": "Petbusinessowners"
}
}
}
The response body contains the associated ProductTemplate resource. The enabled property displays a Boolean
value indicating whether the product is enabled or disabled.
{
"data": {
"attributes": {
"abbreviation": "PBP",
"codeIdentifier": "PetBusinessOwners",
"description": "Pet Business Owners",
"enabled": false,
"id": "Petbusinessowners",
"name": "Petbusinessowners",
. . .
},
. . .
}
}
Generating code from a visualized product

In PolicyCenter, authorized users can generate several types of code from a visualized product.
Code type Description Installed location in PolicyCenter

Base product All code necessary to enable complete /pc/app-pc/pc-apd-genlob-content/config/extensions/
code product functionality in PolicyCenter /pc/app-pc/pc-apd-genlob-content/config/locale/
/pc/app-pc/pc-apd-genlob-content/config/lookuptables/
/pc/app-pc/pc-apd-genlob-content/config/resources/
/pc/app-pc/pc-apd-genlob-content/config/web/
/pc/app-pc/pc-apd-genlob-content/displaynames/
/pc/app-pc/pc-apd-genlob-content/gsrc/
API code API-related code (Swagger, schema, /pc/app-pc/pc-lob-{lobId}

mapper, updater, and resource files)
API test code API test stubs, using the Karate testing /pc/apitestbench/customer-api/src/test/java/gw/pc/
framework (these tests belong to the customer/api/lob/{lobId}
customer to maintain and are not
considered product)
External A function stub that can be used to /pc/app-pc/pc-apd-genlob-content/config/extensions/
hook in code extensions
({lobId} refers to the three-character abbreviation used in LOB names, such as "BOP")
To generate code from a visualized product, authorized callers can submit a POST request to the /
productdefinition/v1/product-templates/{productId}/codegen endpoint.
The request body can include the generationMode property, set to one of the following values:
• ALL: Generate API and product base code
• API_CODE: Generate code for the API only
• BASE_CODE: Generate product base code only
• EXTERNAL: Generate extensions code only
By default, this value is set to ALL.
The following code block displays a request body for generating the API code for a Pet Business Owners product:
{
"data": {
"attributes": {
"productId": "Petbusinessowners"
"generationMode": "API_CODE"
}
}
}
Deleting a product template

To delete a product template, authorized callers can submit a business action POST to the /
productdefinition/v1/product-templates/{productId}/delete endpoint.
Generating endpoints for specific products

Insurers may have installed products that were not originally developed in Advanced Product Designer. This
includes the "externally managed" products in the base configuration and products that came from Standards-Based
Templates (SBTs). These products do not come with LOB-specific endpoints. And without these endpoints, you
cannot create policies for these products through Cloud API.
If you want to create policies for these products through Cloud API, you can generate LOB-specific endpoints for
them. However, these products predate the release of Advanced Product Designer and Cloud API. Therefore, some
minor configuration is required to ensure the products work as expected.
The following sections describe how to generate LOB-specific endpoints for specific products.
The base configuration Personal Auto product

To generate endpoints for the Personal Auto line of business, you must:
1. Generate an APD template from the existing product.
2. Modify the template to align naming in the original Cloud API version of the product.
3. From APD, install the system API code.
4. Set the product configuration to use the installed resources.
5. Modify the VehicleDriverExtResource class.
Step 1: Generate an APD template from the existing product

First, you must generate an APD template from the existing Personal Auto product. This is done through the
PolicyCenter user interface.
1. If necessary, set Options→Preferences→Product Design Mode to Developer, and then click Update.
2. Select Administration→Product Management→Externally Managed. This pane contains a list of products that
have been installed by means other than APD.
3. In the Installed Products pane, select "Personal Auto".
4. In the Details pane, click Extract APD Representation. PolicyCenter generates the APD template and stores it in
the <USER_HOME>/Downloads directory.
Step 2: Modify the template

The Personal Auto product predates Cloud API. Therefore, there are a small number of names in the product that do
not align with Cloud API naming. You must modify the template to bring these values into alignment.
1. Open the template generated in the previous step.
2. Find the following tag and change it to the following value. (There is only one instance of this tag.)
a. Original value: <TypeName>VehicleDriver</TypeName>

b. Modified value: <TypeName>Driver</TypeName>
3. Find the following tag and change it to the following value. (There is only one instance of this tag.)
a. Original value: <TypeName>PersonalVehicle</TypeName>
b. Modified value: <TypeName>Vehicle</TypeName>
4. Save the template.
Step 3: Install the system API code
Next, you must import the modified template into Advanced Product Designer and then install the "system API
code".
Note: In this step, you are installing the system API code only. Do not install the entire product.
Installing the entire product could overwritten existing logic, which would result in the product
behaving in unexpected ways.
1. On the Product Management screen, click the APD Managed tab.
2. Click Import from Template.
3. Click Browse. Select the template to import.
4. Click Update. APD imports the product template. Once the import is complete, the product is listed on the
APD Managed tab.
5. Select the imported template from the list.
6. On the Details tab below the list, select Generate Product Code→System APIs→System APIs - Code. APD
shows the Review Product Elements screen.
• You may see warnings about naming conflicts for the NumAddInsured and PatternCode fields. You can
ignore these warnings.
7. Click Complete Generation. In the confirmation dialog box, click OK.
Step 4: Set the product configuration to use the installed resources
A given product can have two sets of artifacts:

• Visualized artifacts are created when a product is imported from a template or mind map.
• Finalized artifacts are created when a product is installed.
Calls from Cloud API can use only one set of artifacts. Every product has an Enabled for REST API flag. When a
single product has both sets of artifacts, this setting determines which set to use for incoming Cloud API calls.
• If the flag is set to Enabled, the visualized set is used.
• If the flag is set to Disabled, the finalized set is used.
By default, this flag is set to Enabled. This means that, by default, the Personal Auto line will use the artifacts
generated when the template was imported in the previous step. To make incoming calls use the original installed
artifacts, you must disable this flag.
1. If you have not done so already, set Options→Preferences→Product Design Mode to Developer, and then click
Update.
2. Navigate to the Product Management screen.
3. Select the product. In the Details tab below the list of products, click Edit Product. PolicyCenter shows the
Product Definition screen for that product.
4. Set Enabled for REST API to Disabled.
5. Click Save.
This setting does not take effect until PolicyCenter is restarted, which is done in the final step.

Step 5: Modify the VehicleDriverExtResource class

During system API code installation, APD generates several artifacts for the new product. For the base configuration
Personal Auto product, one of these artifacts is the VehicleDriverExtResource class, located in the
gw.rest.ext.pc.policyperiod.pa.v1.driver package.
The initial version of this class is empty. Guidewire recommends replacing the class with the code provided below
for the following reasons.
• The override of the finishCreate function ensures that the vehicle driver is linked to the parent PALine object.
This is necessary for certain behaviors, such as some of the base configuration Personal Auto screens in the user
interface.
• The override of the applyPatchForCreate function is not required, but it is recommended to ensure there are no
duplicate driver values.
package gw.rest.ext.pc.policyperiod.pa.v1.driver
uses gw.api.modules.rest.framework.v1.batch.BatchUpdateMap
uses gw.api.modules.rest.framework.v1.exceptions.LocalizedExceptionUtil
uses gw.api.modules.rest.framework.v1.json.DataEnvelope
uses gw.rest.core.pc.policyperiod.v1.JsonConstants#DATA_ATTRIBUTES
uses gw.rest.core.pc.policyperiod.v1.JsonConstants.VehicleDriver#POLICY_DRIVER
@Export
class VehicleDriverExtResource extends VehicleDriverGenResource {
override function finishCreate(data : DataEnvelope, batchUpdateMap : BatchUpdateMap) {
super.finishCreate(data, batchUpdateMap)
var driver = this.Driver.PolicyDriver

driver.PersonalAutoLine = this.Parent.Vehicle.PALine
}
override function applyPatchForCreate(data : DataEnvelope, batchUpdateMap : BatchUpdateMap) {

super.applyPatchForCreate(data, batchUpdateMap)
// Ensure there are no duplicate PolicyDriver values

var pcr = Driver.PolicyDriver
var duplicate = Parent.Vehicle.Drivers.firstWhere(\d -> d.PolicyDriver == pcr && d != Driver)
if (duplicate != null) {
throw LocalizedExceptionUtil.badInputInBody({DATA_ATTRIBUTES, POLICY_DRIVER}.join("."),
"Rest.PolicyPeriod.V1.PolicyContactJsonValueResolver.Duplicate",
{duplicate.PolicyDriver.AccountContactRole.AccountContact.Contact.RestId, "driver", "vehicle"})
}
}
}
Step 6: Restart PolicyCenter

To finish the deployment of all new resources, you must restart PolicyCenter.
Generic endpoints in Personal Auto submissions

The Personal Auto product, as designed in the base configuration, stores some auto-specific information in resources
that are not LOB-specific.
For example, the following auto-specific fields exist on the PolicyContact resource and are accessed using the
generic /jobs/{jobId}/contacts endpoints:
• applicableGoodDriverDiscount
• dateCompletedTrainingClass
• goodDriverDiscount
• licenseNumbr
• licenseState
• numberOfAccidents
• numberOfViolations
• policyNumberOfAccidents
• policyNumberOfViolations
• trainingClassType
• yearLicensed
Therefore, when modifying a base configuration Personal Auto submission, you need to use a mix of LOB-specific
endpoints and generic endpoints.
Composite request submission example

You can test your work by executing the following composite request. This is an end-to-end test that 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.
10. Quotes the job.
{
"requests": [
{
"method": "post",
"uri": "/account/v1/accounts",
"body": {
"data": {
"attributes": {
"firstName": "Tamsin",
"lastName": "Tester",
"primaryAddress": {
"state": {
"code": "CA"
}
}
},
"state": {
"code": "CA"
}
},
"producerCodes": [
{
"id": "pc:16"
}
],
"code": "other"
}
}
}
},
"vars": [
{
"name": "accountId",
},

{
"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": {
}
}
}
},
"vars": [
{
"name": "jobId",
}
]
},
{
"method": "patch",
"uri": "/job/v1/jobs/${jobId}/questions",
"body": {
"data": {
"attributes": {
"answers": {
"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",
}
]
},
{
"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"
},
"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"
}
]
}


Part 8
Generating endpoints for custom

entities
The system APIs in InsuranceSuite Cloud API have a set of default behaviors in the base configuration. However,
through configuration, their behaviors can be modified.
The following topics discuss how insurers can configure system API behavior. This includes generating endpoints
for custom entities by using the REST endpoint generator.
chapter 50
The REST endpoint generator
The REST Endpoint Generator is a tool that insurers can use to create a set of generated endpoints for a custom data
model entity. The tool generates a series of files that define the majority of the functionality for the endpoints.
However, the insurer must complete some additional configuration.
• This topic provides an overview of the REST Endpoint Generator.
• For more information on how to run the Rest Endpoint Generator, see “Running the REST endpoint generator”
on page 353.
• For more information on configuring the resource definition files, see “Configuring the resource definition files”
on page 353.
• For more information on configuring the glue and impl classes, see “Configuring glue and impl classes for
generated endpoints” on page 353.
• For more information on configuring authorization, see “Configuring authorization for generated endpoints” on
page 353.
REST endpoint generator overview

Insurers typically extend the data model of an InsuranceSuite application with new entities specific to their business
model. These data model entities are referred to as custom entities.
Insurers may want to expose some of these custom entities to Cloud API so that caller applications can:
• Retrieve data stored in these entities.
• Create new instances of these entities.
• Modify or delete these entities as needed.
To address this need, Cloud API includes a REST endpoint generator. The REST endpoint generator is a tool that
generates a set of CRUD endpoints for a custom entity.
Architecture of custom CRUD endpoints

CRUD endpoints is a term that refers to the endpoints that let you GET a collection of a given resource type and that
let you GET, POST, PATCH, or DELETE an element of that resource type. The term "CRUD" is an acronym for
Create Read Update Delete.
High-level architecture
The following diagram depicts the high-level architecture of a set of custom CRUD endpoints within Cloud API.
These endpoints are for a custom entity whose name is CustomEntity_Ext.
The REST endpoint generator 385
There are five CRUD endpoints, but they do not all interact with the same type of resource.
• The first two CRUD endpoints are for GET (for a collection) and POST. These endpoints interact with a
collection resource whose name is customEntitiesExt. (Note that the resource name uses a plural term.)
• The final three CRUD endpoints are for GET (for a specific element), PATCH, and DELETE. These endpoints
interact with an element resource whose name is customEntityExt. (Note that the resource name uses a singular
term.
The components of the architecture map to each other in the following ways:
• The collection resource (customEntitiesExt) makes use of the element resource.
• The element resource (customEntityExt) maps to the data model entity.
• The data model entity (CustomEntity_Ext) is used to retrieve data from and send data to the database.
Files that define the architecture

The CRUD endpoint architecture is defined in a series of files, as depicted in the following diagram.
The swagger file defines the endpoints themselves (the paths, operations, and associated resources).
The schema file defines the schema used by the element and collection resources.
The mapping file defines how information is mapped from the data model entity to the element resource. This
information is used for GETs, and for the responses of POSTs and PATCHes.
The updater file defines how information is mapped from the element resource to the data model entity. This
information is used for POSTs and PATCHes.
386 chapter 50: The REST endpoint generator
The eti file defines the data model entity.

There are also a series of files that define logic for how the endpoints interact with the application.
• The apiconfig file is a "glue" file. One of its purposes is to map both the element resource and collection
resource to corresponding "Resource" Gosu files. For collection resources, this file can also specify a default sort
order.
• There are two "impl" files that define implementation details.
◦ The <collection>Resource.gs file is a Gosu file that defines required behaviors for working with collections.
This includes behaviors such as how to retrieve the collection from the database.
◦ The <element>Resource.gs file is a Gosu file that defines required behaviors for working with elements. This
includes behaviors such as how to initialize a new element.
• There are two sets of "auth" files that define authorization.
◦ There are one or more role.yaml files that define endpoint access for callers of the endpoint.
◦ There are a set of access.yaml files that define resource access for callers of the endpoint.
Architecture and the REST endpoint generator

When you run the REST endpoint generator for a given custom entity, the tool creates or modifies the files needed to
support CRUD endpoints for the custom entity. The following diagram summarizes the files that are created or
modified when running the tool for an entity whose name is CustomEntity_Ext.
Note the following conventions:

• <API> refers to the name of the API in which the endpoints have been placed.
• The data model entity file (CustomEntity_Ext.eti) appears in orange because it is not created or modified by
the REST endpoint generator. It must exist before the generator is run.
• The swagger file (<API>_ext-1.0.swagger.yaml) appears in brown because it is modified by the REST
endpoint generator, but further configuration is not required.
• The remaining files, which appear in blue, are created or modified by the REST endpoint generator. Further
configuration to these files is either required or recommended.
The REST endpoint generator 387

REST endpoint generator restrictions

The REST endpoint generator can be used only on non-subtyped custom entities.
• You cannot use the REST endpoint generator for base configuration entities.
◦ If a base configuration data model entity already has associated endpoints, you can add fields to the
corresponding resource. For more information, see “Configuring schemas” on page 325. But you cannot
otherwise configure those endpoints.
◦ However, if a base configuration data model entity does not have any associated endpoints, you cannot use the
REST endpoint generator to create endpoints for it.
• You cannot use the REST endpoint generator for custom entities that are subtypes.
When generating custom resources, if the custom entity does not have an "_Ext" suffix, the REST endpoint
generator appends an "Ext" or "ext" suffix to the name of the resource in file names and file contents.
The REST endpoint generator generates CRUD endpoints only. It cannot be used to create business action POSTs,
such as an /assign or /submit endpoint.
Special use cases

Integration graphs
An integration graph is a data model graph used by Guidewire App Events. It defines a set of business information
to be sent to an external application as part of outbound integrations. For example, the Claim graph defines what
information to send about a claim. For more information on integration graphs, see the App Events Guide.
When you generate endpoints for a custom entity, you can also add the custom resource to an integration graph if the
resource has a parent resource and that parent resource belongs to the integration graph. For more information, see
“Additional considerations for generated endpoints” on page 353.
Parent entities with additional implications

There is special functionality tied to the Policy entity and all of its child entities. If the Policy entity (or one of its
children) is the parent for the custom entity, the REST endpoint generator executes endpoint generation in a special
way. For information on these differences, see “Additional considerations for generated endpoints” on page 353.
Root resources
In most cases, when you generate endpoints for a custom entity, the custom entity is child to some existing parent
entity. You access the associated REST resource through that parent entity.
For example, suppose you have a custom entity named CustomEntity_Ext. It is a child of the existing Activity
entity. Information about CustomEntity_Ext instances are accessed through the parent Activity. In this case, the
endpoints have this structure:
• GET /common/v1/activities/{activityId}/custom-entity-ext
• GET /common/v1/activities/{activityId}/custom-entity-ext/{CustomEntityExtID}
However, it is possible to generate endpoints for a custom entity as a root resource. In this case, you access the
associated REST resource directly.
For example, suppose you have a custom entity named CustomEntity_Ext. The endpoints are generated with the
associated resource being a root resource. In this case, the endpoints have this structure:
• GET /common/v1/custom-entity-ext
• GET /common/v1/custom-entity-ext/{CustomEntityExtID}
For more information on generating endpoints for root resources, see “Additional considerations for generated
endpoints” on page 353.
388 chapter 50: The REST endpoint generator
chapter 51
Running the REST endpoint generator
The REST Endpoint Generator is a tool that insurers can use to create a set of generated endpoints for a custom data
model entity. The tool generates a series of files that define the majority of the functionality for the endpoints.
However, the insurer must complete some additional configuration.
This topic discusses how to run the REST endpoint generator. It creates or modifies the files highlighted in the
following architecture diagram.
Configuration of the files are discussed in other parts of the documentation.

• For an overview of the REST Endpoint Generator, see “The REST endpoint generator” on page 353.
on page 353.
page 353.
Running the REST endpoint generator 389
Issues to consider before running the generator

The REST endpoint generator asks a series of questions, which determine the behaviors of the endpoints. Some
questions have significant implications on this behavior. Guidewire encourages developers to consider the following
issues prior to running the generator.
The API for the new endpoints

You must identify which API (such as Common or Admin) to add the endpoints to.
The Job API
Guidewire recommends adding endpoints to the Job API only if the underlying entity is effective-dated. Adding
endpoints to the Job API for non-effective-dated entities is not recommended.
When you add endpoints to the Job API, the REST endpoint generator also adds the corresponding GET endpoints
to the Policy API. The generator also adds appropriate PpolicyCenter-specific query parameters, such as asOfDate
and jobVersion, to the endpoints.
Any roles that are given GET access to endpoints in the Job API will also have access to the GET endpoints in the
Policy API.
Schemas, mappers, updaters, Swagger parameters, and Swagger request/response envelope definitions are added to
the policyperiod files, rather than job or policy files.
The Policy API
You cannot add endpoints directly to the Policy API. The only way to add endpoints to the Policy API is to add them
to the Job API. Any GET endpoints added to the Job API are automatically copied to the Policy API.
The Account API, Admin API, and Common API
Endpoints for a custom entity can be added to the Account API, Admin API, or Common API only if the custom
resource is not effective-dated.
The Composite API, the Test Util API, and the Product Definition API
You cannot add custom endpoints to these APIs.
Summary of entity types and APIs
API Add endpoints for effective-dated Add endpoints for non- effective-dated
entities? entities?
Account API No Yes
Admin API No Yes
Common API No Yes
Composite API No No
Job API Yes Not recommended
Policy API Yes, but only by adding them to the Job No
API. Endpoints cannot be added directly
to the Policy API.
Product Definition API No No
Test Util API No No
390 chapter 51: Running the REST endpoint generator

The parent of the custom resource

In most cases, the custom entity is the child of an existing entity (such as a claim or an account). The custom entity
may be a direct child of a single parent. But the custom entity could also be part of a hierarchy that is several levels
deep. When the custom entity has multiple ancestors, you have a choice in the structure of the endpoint path.
For example, suppose you have a CustomEntity_Ext entity which is the child of AccountContact, and
AccountContact is the child of Account. When you generate the endpoints, you can make the custom resource a
descendent of its immediate parent (AccountContact), or a distant ancestor (Account).
Choosing the immediate parent

If you choose the immediate parent, then your endpoints would look like this:
• GET /account/{accountId}/contacts/{contactId}/custom-entities-ext
• POST /account/{accountId}/contacts/{contactId}/custom-entities-ext
• GET /account/{accountId}/contacts/{contactId}/custom-entities-ext/{customEntityExtId}
• PATCH /account/{accountId}/contacts/{contactId}/custom-entities-ext/{customEntityExtId}
• DELETE /account/{accountId}/contacts/{contactId}/custom-entities-ext/{customEntityExtId}
With this approach, you cannot retrieve all CustomEntity_Ext instances for a single Account in one call. You would
need to make multiple calls, one for each AccountContact.
When you create a new CustomEntity_Ext, the immediate parent (the AccountContact) is specified in the URL.
Therefore, the new resource is linked to its immediate parent.
Choosing a distant ancestor

If you choose a distant ancestor, such as Account, then you endpoints would look like this:
• GET /account/{accountId}/custom-entities-ext
• POST /account/{accountId}/custom-entities-ext
• GET /account/{accountId}/custom-entities-ext/{customEntityExtId}
• PATCH /account/{accountId}/custom-entities-ext/{customEntityExtId}
• DELETE /account/{accountId}/custom-entities-ext/{customEntityExtId}
With this approach, you can retrieve all CustomEntity_Ext instances for a single Account in one call.
When you create a new CustomEntity_Ext, the immediate parent (the AccountContact) is not specified in the URL.
Therefore, the new resource is not automatically linked to its immediate parent. (It may be possible to link the new
resource to its immediate parent by explicitly adding it to the request payload.)
Making the choice

From a technical standpoint, either choice is valid. The best choice depends on how you need to perform GET and
POST methods.
Populating collections
One of the GET endpoints retrieves a collection. This collection can be retrieved using either a Java stream or a
Gosu query.
A stream loads the entire collection into memory before manipulating it. Streams have the advantage of being Java
objects, which developers may be more familiar with. Filtering and sorting may be easier with stream-backed
resources as the whole collection is loaded into memory. However, streams may degrade performance if the size of
the collection is too large.
Gosu queries are expressions that are converted into SQL queries. Queries have a maximum number of elements
that are loaded into memory at one time. Queries have the advantage of preserving performance if the size of the
entire collection is large, as the collection is loaded in portions. However, developers who are not familiar with Gosu
may find it harder to write complex query logic.
If the collection is likely to be large, Guidewire recommends using a Gosu query. If the collection is not likely to be
large, you can choose whichever type of object they prefer to work with.
With Java streams, you will need to write code to populate the stream. This is easy to do when the parent entity has
an array of custom entities, as the array can be converted into a stream. Therefore, if you decide to use streams, you
may want to add an array of custom entities to the parent, even if the application does not otherwise require an array.
Additional considerations
The REST endpoint generator expects custom entities to conform to the naming convention of starting or ending
with "Ext". (This convention is designed to prevent custom entities from conflicting with base configuration entities
added in future releases.) If the custom entity does not start or end with Ext, the REST Endpoint Generator adds an
"ext" suffix to the name. For example, suppose you had a custom entity named CustomEntity. After the REST
endpoint generator runs:
• The element resource is named CustomEntityExt
• The collection resource is named CustomEntitiesExt
The REST endpoint generator provides a default name for the resource collection. Guidewire recommends naming
this using the plural form of the custom entity name. The REST endpoint generator attempts to guess the correct
plural. If the guess is in correct (such as guessing CustomChildsExt instead of CustomChildrenExt), you can
modify the default.
You must identify the API roles that will have GET, POST, PATCH, and DELETE access to the custom endpoints.
You can add the custom resource to an integration graph. For more information, see “Additional considerations for
Effective-dated entities
Guidewire recommends added only effective-dated entities to the Job API. Effective-dated entities use the
PolicyCenter-specific EffDatedRestElementResource and EffDatedRestListCollectionResource classes.
When you generate endpoints for an effective-dated entity, the following prompts are suppressed:
• The prompt asking if the resource is a root resource or a child resource.
◦ Effective-dated entities must be child to an existing parent resource.
• The prompt asking if the collection resource is backed by a stream or a query.
◦ Effective-dated entities are always assumed to be stream-backed resources.
• The prompt asking if the resource is to be added to an integration graph.
◦ Effective-dated entities are always added to the policyperiod graph.
Running the REST endpoint generator

You can run the REST endpoint generator either from Studio or from a command prompt. Once you start the REST
endpoint generator, you cannot stop it until either it completes or you force it to quit (such as by pressing CTRL+C
in a command prompt).
Running the REST endpoint generator from Studio

You can run the REST endpoint generator from Studio by creating a "run configuration" for it.
Create a run configuration for the REST endpoint generator

Procedure
1. In Studio, select Run→Edit Configurations. Studio opens a Run/Debug Configuration dialog box.
2. In the upper right corner of the dialog box, click the +. In the Add New Configuration popup, click
Application.
3. Provide the following values for each field. Note that some fields in the dialog box do not have labels:
a. Name: RESTEndpointGenerator
b. JDK/JRE field: (use the default value)
c. VM options:
-server
-ea
-Xdebug
-Djava.awt.headless=true
-Dgw.port=8180
-Xmx4g
-Dgw.server.mode=dev
-Dgwdebug=true
-Dgw.webapp.dir=idea/webapp
-Dgw.classpath.jar=true
-Dgw.plugins.gclasses.dir=idea-gclasses
-DgosuInit.supportDiscretePackages=true
d. Main class: com.guidewire.tools.rest.RestEndpointGenerator

e. Program arguments: (blank)
f. Working directory: (use the default value)
g. Environment variables: (blank)
4. Click OK.
Use the run configuration to run the REST endpoint generator

About this task
1. Start the application.
2. In Studio, in the upper right-hand corner, there is a drop-down list. (By default, it is set to "Drop DB".) Set the
value to "RESTEndpointGenerator".
3. Click the green play button to the right of the drop-down list.
The REST endpoint generator loads and then displays the first prompt in the console window at the bottom of the
Studio interface. You can enter responses in this window. For a list of the prompts, see “The REST endpoint
generator prompts” on page 385.
The REST endpoint generator loads the entire type system. Therefore, there may be several minutes between
starting the generator and the appearance of the first prompt.
Running the REST endpoint generator from the command prompt

From the installation directory, open a command prompt and enter the following:
gwb restEndpointGenerator
The REST endpoint generator loads and then displays the first prompt. For a list of the prompts, see .
The REST endpoint generator loads the entire type system. Therefore, there may be several minutes between
executing the command and the appearance of the first prompt.
The REST endpoint generator prompts

The following section lists the prompts for the general case of generating endpoints for a generic child resource. All
responses are case-sensitive.
Which data model entity would you like to generate endpoints for?
Specify the custom entity name.

If the specified entity has a name that does not start or end with "Ext", then an additional prompt identifies that "Ext"
will be added to the resource name. You must acknowledge this by entering "y". If you do not enter "y", the
generator throws an illegal state exception and stops running.
The default plural for this entity is <defaultValue>. If you want to use a different plural,
specify it and press Enter. To accept the default, just press Enter.
Specify a custom name for the collection resource, or press Enter to accept the default name.
Which API should the endpoints be added to?
Specify the API name. The technical name is specified in lower case, such as "common" for the Common API or
"admin" for the Admin API.
Each API has restrictions and recommendations around what can be added to it:
• Endpoints for effective-dated entities can be added only to:
◦ Job API (the generated GETs are also added to the Policy API)
• Endpoints for non-effective-dated entities can be added only to:
◦ Account API
◦ Admin API
◦ Common API
• Endpoints cannot be added to:
◦ Composite API
◦ Product Definition API
◦ Test Util API
(Technically speaking, non-effective-dated entities can be added to the Job API. But Guidewire does not recommend
doing this.)
Is the <CustomEntity> entity at the root of the endpoint path (GET /activities)?
(y = yes; n = no, it is a child of some other entity (GET /activities/{activityId}/notes))
Enter "n" to make the custom resource a child of some existing parent resource. (This prompt is not presented for
effective-dated entities. Effective-dated entities cannot be root resources.)
For more information on creating root resource endpoints, see “Additional considerations for generated endpoints”
on page 353.
What is the resource name of the parent?
Enter the resource name of the parent.

• This is the value of the resourceType from the parent resource's schema.
• This must be an element resource (such as Activity), not a collection (such as Activities).
• In order to generate child endpoints, there must already be a set of CRUD endpoints for the parent resource.
Be aware that, for most endpoints, the resource name is the same as what appears in the endpoint path. For example,
the resource name for GET /activities/{ActivityId} is Activity. But sometimes, the endpoint path differs
from the resource name. For example, the resource name for GET /contacts/{contactId} is not Contact, but
rather AccountContact. To verify you are using the correct name, check the resourceType from the parent
resource's schema.
Is the collection resource backed by a (s)tream or (q)uery?
Select whether your collection is loaded using a Java stream or a Gosu query. (This prompt is not presented for
effective-dated entities. Effective-dated entities are always backed by streams.)
Which roles can access the GET collection and GET element endpoint?
If you do not want to specify roles, just press Enter.
The REST endpoint generator lists the available roles. Enter a comma-separated list of roles that will have GET
access.
Any roles that are given GET access to endpoints in the Job API will also have access to the GET endpoints in the
Policy API.
Note that you do not need to answer any of the authorization prompts. You can press Enter for each prompt.
However, this only bypasses the coding done by the REST endpoint generator. This does not bypass the need to
configure authorization for the endpoints.
Which roles can access the POST collection endpoint? If you do not
want to specify roles, just press Enter.
The REST endpoint generator lists the available roles. Enter a comma-separated list of roles that will have POST
access. Note that GET access is required for POST access. Thus, any role which was not given GET access cannot
be given POST access.
Which roles can access the PATCH element endpoint? If you do not
The REST endpoint generator lists the available roles. Enter a comma-separated list of roles that will have PATCH
access. Note that GET access is required for PATCH access. Thus, any role which was not given GET access cannot
be given PATCH access.
Which roles can access the DELETE element endpoint? If you do not
The REST endpoint generator lists the available roles. Enter a comma-separated list of roles that will have DELETE
access. Note that GET access is required for DELETE access. Thus, any role which was not given GET access
cannot be given DELETE access.
Should <CustomEntity> be added to an integration graph?
Enter "y" or "n". For more information on adding custom resources to integration graphs, see “Additional
considerations for generated endpoints” on page 353.
Completion of the script

After the REST endpoint generator script successfully completes, it lists information about the files it created or
modified.
2022-03-18 16:42:42,817 INFO Beginning endpoint generation
2022-03-18 16:42:42,818 INFO Generating resource classes
2022-03-18 16:42:42,832 INFO Modifying configuration file <api_collection>_ext-1.0.swagger.yaml
2022-03-18 16:42:42,868 INFO Modifying configuration file <api_collection>_ext-1.0.schema.json
2022-03-18 16:42:42,877 INFO Modifying configuration file <api_collection>_ext-1.0.mapping.json
2022-03-18 16:42:42,880 INFO Modifying configuration file <api_collection>_ext-1.0.updater.json
2022-03-18 16:42:42,885 INFO Modifying configuration file shared_ext-1.0.apiconfig.yaml
2022-03-18 16:42:42,903 INFO Modifying configuration file default_ext-1.0.access.yaml
2022-03-18 16:42:42,907 INFO Modifying configuration file internal_ext-1.0.access.yaml
2022-03-18 16:42:42,909 INFO Modifying configuration file accountnumbers_ext-1.0.access.yaml
2022-03-18 16:42:42,917 INFO Modifying configuration file <role>.role.yaml
2022-03-18 16:42:42,939 INFO Finished endpoint generation
Completing the configuration

Several of the files that are created or modified by the REST endpoint generator require further configuration. For
each file requiring configuration, the tool adds one or more "TODO RestEndpointGenerator" comments to help
identify where configuration is needed.
on page 353.
• For more information on configuring the glue and impl files, see “Configuring glue and impl classes for
page 353.

chapter 52
Configuring the resource definition

files
The REST Endpoint Generator can create a set of generated endpoints for a given data model entity. Most of the
files generated by the REST Endpoint Generator are incomplete and require further configuration.
This topic discusses how to configure the resource definition files. They are the files highlighted in the following
architecture diagram.
Configuration of the other files are discussed in other parts of the documentation.
on page 353.
Configuring the resource definition files 397

page 353.
The resource definition files

The schema, mapping, and updater files
For a given Cloud API resource, there are three files that define the structure of the resource and how it connects to
the corresponding data model entity:
• The schema file, which defines the schema used by the element and collection resources.
• The mapping file, which defines how information is mapped from the data model entity to the element resource.
This information is used for GETs, and for the responses of POSTs and PATCHes.
• The updater file, which defines how information is mapped from the element resource to the data model entity.
This information is used for POSTs and PATCHes.
In most cases, the files and modifications made by the REST endpoint generator are not complete. Developers must
provide additional code. The places where additional coding is needed are flagged with the following comment:
TODO RestEndpointGenerator
You can search for these "TODO RestEndpointGenerator" comments in Studio to complete the configuration.
Common patterns used in the schema, mapping, and updater files

Generally speaking, fields in a data model entity follow one of the behaviors listed in the following table. For each
behavior, there is a pattern for how that field is referenced in the schema definition files.
Field behavior Example Schema file Mapping file Updater file

Field is not exposed to Application internal Omitted Omitted Omitted
Cloud API information, such as
<entity>.CreateUser
Field is read-only The <entity>.id field Included; declared as Included Omitted

readOnly
Field must be set Claim.LossDate Included; declared as Included Included

during creation and requiredForCreate,
cannot be changed x-gw-nullable:
thereafter false, and createOnly
Field must be set Document.Status Included; declared as Included Included

during creation, but can requiredForCreate,
be changed later and x-gw-nullable:
false
Field can be set or Activity.Descriptio Included Included Included

omitted during n
creation, and can later
be changed
The swagger file

There is also a swagger file, which defines the endpoints themselves (the paths, operations, and associated
resources). The REST endpoint generator adds code to this file. There is no requirement to modify this file, and
there are no "TODO RestEndpointGenerator" comments in this file. However, a developer may wish to modify the
file for the following reasons:
• To change the API documentation text, such as the title and description of the endpoints
• To remove an operation, such as DELETE
398 chapter 52: Configuring the resource definition files
Configuring the schema file for generated endpoints

Within the context of Cloud API, a schema file defines the structure of one or more resources. This information is
used for GETs, POSTs, and PATCHes.
The following sections provide an overview of configuring schema files for generated endpoints. For a complete
description of how to configure schema files, see “Configuring schemas” on page 325.
Overview of schema file syntax

A schema file contains a definitions section that lists one or more schemas. Each schema is used to structure an
API resource. For each schema, the following attributes are specified:
• A title and description, which is used for API definition documentation.
• The resource type, which is typically set to object.
• A list of properties. Each property includes:
◦ A title and description, which is used for API definition documentation.
◦ A type, which defines the JSON datatype of the property (for scalar values).
◦ A ref, which defines the URI reference for the property (for compound values such as typekeys).
◦ Optional attributes as needed for the business functionality of the property.
For example, the following is a portion of the schema for the base configuration Activity resource:
"Activity": {
"title": "Activity",
"description": "An Àctivity` is an assignable item that represents a task to be done, a decision to be made, or
information to be aware of",
"type": "object",
"properties": {
"activityPattern": {
"title": "Activity pattern",
"description": "The code of the ÀctivityPattern` used to create this activity and set its initial values",
"type": "string"
...
}
},
Modifications made to the schema file

The base configuration includes a set of API-specific extension schema files. The purpose of these files is to define
schema information for custom resources for a given API. These files are named using the pattern
<API>_ext-1.0.schema.json, where <API> is the internal name of the API. For example, the
common_ext-1.0.schema.json file is used to define schema information for custom resources in the Common API.
You can access extension schema files in Studio through the integration -> schemas -> ext -> <API>.v1 node.
(There is an exception to the previous statement. When you add endpoints to the Job API, schema modifications are
not made to a job_ext-1.0.schema.json file, but rather to the policyperiod_ext-1.0.schema.json file.)
When you generate endpoints for a custom entity, the REST endpoint generator adds the following code to the
relevant extension schema file:
"<resourceName>": {
"title": "<custom entity name>",
"description": "<custom entity name>",
"type": "object",
"properties": {
// TODO RestEndpointGenerator : Add schema properties here
"id": {
"title": "ID",
"description": "The unique identifier of this element",
"type": "string",
"readOnly": true
}
}
}
For example, if you generate endpoints for a CustomEntity_Ext entity, the following is added to the extension
schema file:
"type": "object",
"properties": {
"id": {
"title": "ID",
"type": "string",
"readOnly": true
}
}
}
Note that the REST endpoint generator provides properties information for only one property: id. The developer
is responsible for:
• Deciding which fields from the custom entity must be available to the endpoints.
• Adding mapper information for those fields.
For example, suppose the CustomEntity_Ext entity included three fields:
• CustomDescription (a string)
• IsActive (a boolean)
• ExpirationDate (a datetime)
The developer decides CustomDescription and IsActive must be available to GETs, POSTs, or PATCHes. The
developer would need to add the code shown below in bold.
"type": "object",
"properties": {
"id": {
"title": "ID",
"type": "string",
"readOnly": true
},
"title": "CustomDescription",
"description": "The description for the CustomEntity",
"type": "string"
},
"id": {
"title": "isActive",
"description": "Whether the CustomEntity is active",
"type": "boolean"

}
}
}
The developer also decides ExpirationDate must not be available to GETs and POST/PATCH responses.
Therefore, this field is omitted from the schema.
Syntax for property types

The datatype of each property is specified using either a type attribute or a $ref attribute.
Scalars
If a data model entity field is a scalar, set the type attribute to one of the JSON schema types from the following
table.
Data model datatype Corresponding JSON type Additional required properties

bit boolean
dateonly string An additional "format" property set to

"date"
datetime string An additional "format" property set to
"date-time"
decimal number
integer integer
longint integer
longtext string
mediumtext string
money number
percentage number
shorttext string
text string
varchar string
For example, the CustomEntityExt resource could have the following scalar properties:
"definitions": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"isActive": {
"type": "boolean"
},
"type": "string"
},
"expirationDate": {
"type": "string",
}
}
}
}

Compound datatypes
InsuranceSuite includes several datatypes where multiple values are stored as a unit. This includes the following:
• Typekey (a code and a name)
• MonetaryAmount and CurrencyAmount (a currency and an amount)
• SpatialPoint (a longitude coordinate and a latitude coordinate)
For example, the assignmentStatus property's datatype is a typekey. Thus, the response payload for an activity's
assignment status has two sub-fields:
"code": "pendingassignment",
"name": "Pending Assignment"
},
When you define a schema property for a compound datatype, do not include a type property. In its place, specify a
$ref attribute that specifies an existing definition for the datatype. The following table lists the $ref values for the
common compound datatypes.
Compound datatype $ref value Additional required properties

Typekey #/definitions/TypeKeyReference A x-gw-extensions attribute with a
typelists child attribute that identifies
the relevant typelist.
MonetaryAmount #/definitions/MonetaryAmount
CurrencyAmount #/definitions/CurrencyAmount
SpatialPoint #/definitions/SpatialPoint
...
"typelist": "AssignmentStatus"
}
The mapping for the Contact data model entity's SpatialPoint field (which is a spatial point) looks like this:
"spatialPoint": {
...
"$ref": "#/definitions/SpatialPoint"
}
Additional properties
In a schema file, you must specify the datatype of each property using either a type attribute or a $ref attribute. You
can also add optional attributes. Some attributes are direct children of the property. Others must be declared inside
an x-gw-extensions object.
Some attributes have default values. The defaults are listed in the following tables.
Additional properties that are direct children of the property

readOnly Boolean identifying if the field as read- "readOnly": true
only. (The default is false.)
x-gw-nullable Boolean identifying if the field can be
"x-gw-nullable": false
explicitly set to null. (The default is
true.) See the following "Marking a field

as required" section for more

information.
x-gw-sinceVersion String identifying the first version of the
"x-gw-sinceVersion": "1.1.0"
API to include the property
For example, suppose the CustomEntity_Ext entity has an ExpirationDate field. The corresponding resource
property is read-only and was added in version 1.1.0. The property declaration would be:
"definitions": {
...
"properties": {
...
},
"expirationDate": {
"type": "string",
"readOnly": true,
"x-gw-sinceVersion": "1.1.0"
}
...
Additional properties declared in the x-gw-extension object

createOnly Boolean identifying if the field can be "createOnly": true
specified only when the object is
created. (The default is false.)
filterable Boolean identifying if the filter query "filterable": true
parameter can be used on this field. In
other words, collections can be filtered
using this property. (The default is
false.)
requiredForCreate Boolean identifying if the field must be "requiredForCreate": true

specified when the object is created.
(The default is false.) See the following
"Marking a field as required" section for
more information.
sortable Boolean identifying if the sort query "sortable": true
parameter can be used on this field. In
other words, collections can be sorted
using this property. (The default is
false.)
For example, suppose the CustomEntity_Ext entity has an SeverityType field, which is a typekey set to a value in
the SeverityType typelist. The corresponding resource property must be specified at create time, cannot be
modified after creation, and is both filterable and sortable. The property declaration would be:
"definitions": {
...
"properties": {
...
},
"severityType": {
"typelist": "SeverityType",
"createOnly": true,
"requiredForCreate": true,
"filterable": true,
"sortable": true

}
}
...
Marking a field as required by the database

In the data model, some entity fields are required. You cannot create an instance of the entity without specifying a
value for the field. For example, suppose that an insurer has a business rule stating every activity must have a
completion date. To enforce this, the Activity entity's EndDate field is required.
In a schema, you can mark a resource field as required. To do this, you must set the following properties:
• "requiredForCreate": true
◦ This x-gw-extensions attribute indicates the field must be included in POST payloads.
• "x-gw-nullable": false
◦ This attribute indicates that when the field is specified, its value cannot be set to null
The "requiredForCreate": true expression, by itself, only mandates that the field must be specified in a POST.
There is nothing to prevent a caller from including the field but setting the field's value to null.
The "x-gw-nullable": false expression, by itself, only mandates that if the field is specified, the field's value
cannot be set to null.
By combining the two expressions, you are stating that the field must be specified in a POST and set to a non-null
value, and anytime thereafter that the field is specified, it must be set to a non-null value. This is the equivalence of
setting a data entity field to required.
For example, suppose the CustomEntity_Ext entity has an CustomDescription field, which is a string. The field is
required. The property declaration would be:
"definitions": {
...
"properties": {
...
},
"type": "string",
"x-gw-nullable": false,
}
}
...
Configuring the mapping file for generated endpoints

Within the context of Cloud API, a mapping file contains mappers that define how information is mapped from a
data model entity to the corresponding element resource. This information is used for GETs, and for the responses of
POSTs and PATCHes.

The following sections provide an overview of configuring mapping files for generated endpoints. For a complete
description of how to configure mapping files, see “Configuring schemas” on page 325.
Overview of mapping file syntax

A mapping file contains a mappers section that lists one or more API resources. For each resource, the following
attributes are specified:
◦ Each property includes a path attribute. This is a Gosu expression that is used to populate the value of the
property. Typically, this expression returns a value from the entity defined in the root attribute.
For example, the following is a portion of the mapper for the base configuration Activity resource:
"Activity": {
"properties": {
"closeDate": {
"path": "Activity.CloseDate"
},
"description": {
},
"mandatory": {
},
...
Note the following:

• This resource is defined in the schema who name is Activity (This schema is defined in some other schema.json
file.)
◦ The closeDate property is set to the Activity entity's CloseDate field.
◦ The description property is set to the Activity entity's Description field.
◦ The mandatory property is set to the Activity entity's Mandatory field.
Modifications made to the mapping file

The base configuration includes a set of API-specific extension mapping files. The purpose of these files is to define
mapper information for custom resources for a given API. These files are named using the pattern
<API>_ext-1.0.mapping.json, where <API> is the internal name of the API. For example, the
common_ext-1.0.mapping.json file is used to define mapper information for custom resources in the Common
API. You can access extension mapping files in Studio through the integration -> mappers -> ext -> <API>.v1
node.
(There is an exception to the previous statement. When you add endpoints to the Job API, mapper modifications are
not made to a job_ext-1.0.mapping.json file, but rather to the policyperiod_ext-1.0.mapping.json file.)
relevant extension mapping file:
"<resourceName>": {
"schemaDefinition": "<schemaNameForResource>",
"root": "entity.<customEntity>",
"properties": {
// TODO RestEndpointGenerator : Add mapper properties here
"id": {

"path": "<customEntity>.RestId"
}
}
}
mapping file:
"schemaDefinition": "CustomEntityExt",
"root": "entity.CustomEntity_Ext",
"properties": {
"id": {
"path": "CustomEntity_Ext.RestId"
}
}
}
Note that the REST endpoint generator provides information for only one property: id. The developer is responsible
for:
• Deciding which fields from the custom entity must be available for GETs (and POST/PATCH responses)
• Adding mapper information for those fields.
The developer decides CustomDescription and IsActive must be available to GETs and POST/PATCH responses.
The developer would need to add the code shown below in bold.
"properties": {
"id": {
"path": "CustomEntity_Ext.RestId"
},
},
"isActive": {
"path": "CustomEntity_Ext.IsActive"
}
}
}
The developer also decides ExpirationDate must not be available to GETs and POST/PATCH responses. This field
was presumably omitted from the schema. Therefore, it is also omitted from the mapper.
Mapping syntax for property paths

Scalars
If a data model entity field is a scalar value, you typically set the path property to a field from the data model entity.
No other properties are required. For example:
"description": {
},
Compound datatypes
When you define the mapping for a compound datatype (such as a Typekey, MonetaryAmount, CurrencyAmount, or
SpatialPoint), you must include both the path attribute and an additional mapper attribute. The mapper attribute
specifies the mapper that defines how the compound data type is mapped into its schema. The following table lists
the mapper attribute values for the common compound datatypes.

Typekey #/mappers/TypeKeyReference
MonetaryAmount #/mappers/MonetaryAmount
CurrencyAmount #/mappers/CurrencyAmount
SpatialPoint #/mappers/SpatialPoint
},
Configuring the updater file for generated endpoints

Within the context of Cloud API, an updater file defines how information is mapped from an element resource to the
corresponding data model entity. This information is used for POSTs and PATCHes.
The following sections provide an overview of configuring updater files for generated endpoints. For a complete
description of how to configure mapping files, see “Configuring schemas” on page 325.
Overview of updater file syntax

An updater file contains an updaters section that lists one or more API resources. For each resource, the following
attributes are specified:
◦ Each property includes a path attribute. This defines, for each resource property, the data model entity property
into which the resource field property is to be written.
For example, the following is a portion of the updater for the base configuration Activity resource:
"Activity": {

"properties": {
"description": {
},
"mandatory": {
},
...
Note the following:

• This resource is defined in the schema who name is Activity (This schema is defined in some other schema.json
file.)
◦ The value of the description property is written to the Activity entity's Description field.
◦ The value of the mandatory property is written to the Activity entity's Mandatory field.
Note that there may be properties that appear in the mapping file but not the updater file. This typically occurs with
properties that are read-only. For example, the Activity entity has a closeDate property, which the application sets
when the activity is closed. This property appears in the mapping file, as it can be read. But it does not appear it the
updater file because it cannot be written to.
Modifications made to the updater file

The base configuration includes a set of API-specific extension updater files. The purpose of these files is to define
updater information for custom resources for a given API. These files are named using the pattern
<API>_ext-1.0.updater.json, where <API> is the internal name of the API. For example, the
common_ext-1.0.updater.json file is used to define updater information for custom resources in the Common
API. You can access extension mapping files in Studio through the integration -> mappers -> ext -> <API>.v1
node.
(There is an exception to the previous statement. When you add endpoints to the Job API, updater modifications are
not made to a job_ext-1.0.updater.json file, but rather to the policyperiod_ext-1.0.updater.json file.)
relevant extension updater file:
"<resourceName>": {
"schemaDefinition": "<schemaNameForResource>",
"root": "entity.<customEntity>",
// TODO RestEndpointGenerator : Add updater properties here
"properties": { }
}
updater file:
"properties": { }
}
Note that the REST endpoint generator does not provide any properties information. This is because the only field
that gets added to the schema definition files is the id field. This field is not writeable, so it is not added to the
updater.
The developer is responsible for:
• Deciding which fields from the custom entity must be available for POSTs and PATCHes
• Adding updater information for those fields.


The developer decides CustomDescription and IsActive must be available to POSTs and PATCHes. The
developer would need to add the code shown below in bold.
"properties": {
},
"isActive": {
"path": "CustomEntity_Ext.IsActive"
}
}
}
The developer decides ExpirationDate must not be available to POSTs and PATCHes. The field may appear in the
schema and mapper, as it may be available for GETs. But it is omitted from the updater as it is not available to
POSTs or PATCHes.
Updater syntax for property paths

Scalars
If a data model entity field is a scalar value, you typically set the path property to the field in the data model entity.
No other attributes are required. For example:
"description": {
},
Compound datatypes
When you define the updater for a compound datatype (such as a Typekey, MonetaryAmount, CurrencyAmount, or
SpatialPoint), you must include a valueResolver attribute with a child typeName attribute. This attribute
specifies a resolver, which defines how to map the structure for the compound datatype to the data model entity. The
updater syntax for compound datatypes is:
"<field>": {
"path": "<pathValue>",
"valueResolver": {
"typeName": "<resolverName>"
}
},
The following table lists the resolver names for the common compound datatypes.

Typekey TypeKeyValueResolver
MonetaryAmount MonetaryAmountValueResolver
CurrencyAmount CurrencyAmountValueResolver
SpatialPoint SpatialPointValueResolver
For example, the updater for the Activity resource's assignmentStatus field looks like this:

"valueResolver": {
}
},
Configuring the swagger file for generated endpoints

Within the context of Cloud API, a swagger file defines the endpoints and operations for a given API.
The following sections provide an overview of configuring swagger files for generated endpoints. For a complete
description of how to configure swagger files, see “Configuring schemas” on page 325.
Overview of swagger file syntax

A swagger file contains a paths section that lists one or more endpoint paths. For each path, the following
information is specified:
• Any path or query parameters
• Each operation supported for the path, and information about the operation
Modifications made to the swagger file

The base configuration includes a set of API-specific extension swagger files. The purpose of these files is to define
swagger information for custom resources for a given API. These files are named using the pattern
<API>_ext-1.0.swagger.json, where <API> is the internal name of the API. For example, the
common_ext-1.0.swagger.json file is used to define swagger information for custom resources in the Common
API.
(There is an exception to the previous statement. When you add endpoints to the Job API, swagger modifications are
not made to a job_ext-1.0.swagger.json file, but rather to the policyperiod_ext-1.0.swagger.json file.)
When you generate endpoints for a custom entity, the REST endpoint generator adds code to the corresponding
swagger extension file.
For example, suppose you generate endpoints for a CustomEntity_Ext custom entity. The parent of this entity is
Account, and the endpoints are placed in the Account API. The REST endpoint generator add the following code to
the account_ext-1.0.swagger.json file:
paths:
"/account/{accountId}/custom-entities-ext":
parameters:
- $ref: "#/parameters/accountId"
get:
summary: "Retrieve a collection of custom entities ext"
description: "Retrieve a collection of custom entities ext"
operationId: getCustomEntitiesExt

x-gw-extensions:
childResourceType: CustomEntityExt
operationType: get-collection
resourceType: CustomEntitiesExt
x-gw-parameter-sets: get-collection
responses:
"200":
description: "Successful response"
schema:
$ref: "#/definitions/CustomEntityExtList"
post:
summary: "Create a new custom entity ext"
description: "Create a new custom entity ext"
operationId: createCustomEntityExt
x-gw-extensions:
childResourceType: CustomEntityExt
operationType: post-collection
resourceType: CustomEntitiesExt
parameters:
- name: body
in: body
required: true
schema:
$ref: "#/definitions/CustomEntityExtRequest"
x-gw-parameter-sets: post-collection
responses:
"201":
description: "The details of the newly-created CustomEntityExt"
schema:
$ref: "#/definitions/CustomEntityExtResponse"
"/accounts/{accountId}/custom-entities-ext/{customEntityExtId}":
parameters:
- $ref: "#/parameters/accountId"
- $ref: "#/parameters/customEntityExtId"
get:
summary: "Retrieve details of a custom entity ext"
description: "Retrieve details of a custom entity ext"
operationId: getCustomEntityExt
x-gw-extensions:
operationType: get-element
resourceType: CustomEntityExt
x-gw-parameter-sets: get-element
responses:
"200":
schema:
patch:
summary: "Update a custom entity ext"
description: "Update a custom entity ext"
operationId: updateCustomEntityExt
x-gw-extensions:
operationType: patch-element
parameters:
- name: body
in: body
required: true
schema:
$ref: "#/definitions/CustomEntityExtRequest"
x-gw-parameter-sets: patch-element
responses:
"200":
schema:
delete:
summary: "Delete a custom entity ext"
description: "Delete a custom entity ext"
operationId: deleteCustomEntityExt
x-gw-extensions:
operationType: delete-element
x-gw-parameter-sets: delete-element
responses:
"204":
description: "Successful deletion"

Note that this text is functionally complete and there are no "TODO RestEndpointGenerator" comments in the file.
However, a developer may wish to optionally modify the file.
Modifying API documentation text

Every path and response has summary and description information. This text is used by API definition display
tools, such as Swagger UI. Developers may wish to modify the summary and description values created by the
REST endpoint generator to improve the user experience for other developers who are consuming these endpoints.
Removing operations
The REST endpoint generator always generates a collection endpoint with a GET and POST operation, and an
element endpoint with a GET, PATCH, and DELETE operation. If you do not want any of these operations, you can
remove them from the swagger file.
For example, suppose an insurer wants endpoints to support CustomEntity_Ext, but they do not want to expose the
ability to delete CustomEntity_Ext instances. In this case, the developer could remove the "delete" declaration
from the swagger file.

Several of the files that are created or modified by the REST endpoint generator require further configuration. For
each file requiring configuration, the tool adds one or more "TODO RestEndpointGenerator" comments to help
identify where configuration is needed.
In addition to the resource definition files, you must also configure the glue and impl files and the authorization
files.
• For more information on configuring the glue and impl files, see “Configuring glue and impl classes for
page 353.

chapter 53
Configuring glue and impl classes for

generated endpoints
This topic discusses how to configure the glue and impl class files. They are the files highlighted in the following
on page 353.
on page 353.
Configuring glue and impl classes for generated endpoints 413

page 353.
The glue and impl classes for generated endpoints

The REST endpoint generator creates and modifies a series of files that define logic for how the endpoints interact
with the application.
• The apiconfig file is a "glue" file. It maps both the element resource and collection resource to a "Resource"
Gosu file. For collection resources, this optionally provides a default sort order.
• There are two "impl" files that define implementation details.
◦ The <collection>Resource.gs file is a Gosu file that defines required behaviors for working with collections.
This includes behaviors such as how to retrieve the collection from the database and how to create a minimal
child element.
◦ The <element>Resource.gs file is a Gosu file that defines required behaviors for working with elements. This
includes behaviors such as how to initialize a new element and how to delete one.
In most cases, the files and modifications made by the REST endpoint generator are not complete. Developers must
provide additional code. The places where additional coding is needed are flagged with the following comment:
// TODO RestEndpointGenerator : <context>
You can search for these "TODO comments" in Studio and complete the configuration. The remainder of this topic
explains the configuration needed in every glue and impl file.
Configuring the apiconfig file

The apiconfig file maps both element resource and collection resources to a Resource Gosu file. The apiconfig file
can be used to define the order for your collection response payload.
The REST endpoint generator automatically modifies the apiconfig file to map element and collection resources to
respective Resource Gosu files, but does not add the sort order for your response payload.
Guidewire recommends a default sort order for your collection resources to provide a consistent, deterministic
response payload. Determine the object by which the response payload orders its collection by defining the default
sort order.
Including default sorts in the .apiconfig file

The apiconfig file maps the collection and elements resources of your custom endpoint to its respective Resource
Gosu files. For example,
CustomEntitiesExt:
resource: gw.rest.ext.cc.claim.v1.claims.customentityext.CustomEntitiesExtResource
CustomEntityExt:
resource: gw.rest.ext.cc.claim.v1.claims.customqentityext.CustomEntityExtResource
Append defaultSort under the collection resource to determine the order the sortable attributes are sorted by in the
response payload.
For a given endpoint, you can identify the attributes that are sortable by reviewing the API core schema file
(<api_collection>_ext-1.0.schema.json) in the x-gw-extensions resource.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 the dueDate field returned by the Common API's 
Activity definition.
"dueDate": {
"title": "Due date",
"description": "Date and time by which a person should complete the activity. If not
completed by this time, the activity is considered overdue. Not applicable to activities
that represent events rather than tasks.",
"type": "string",
414 chapter 53: Configuring glue and impl classes for generated endpoints
"x-gw-nullable": true,
"filterable": true,
"sortable": 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.
You can define ascending or descending order via syntax; use - <attributeName> for ascending, and use – "-
<attributeName>" for descending sort order. For example, if you wanted ascending sort order based on the
customDescription attribute in your element and collection, use the following:
CustomEntitiesExt:
defaultSort:
- customDescription
For descending sort order, use the following:

CustomEntitiesExt:
defaultSort:
- "-customDescription"
You can also use multiple attributes to further define the sort order; the first attribute initially defines the sort order,
then the second attribute defines the order of those items, then additional attributes defines the order of those items,
and so forth. For example, if you wanted to sort your response payload first by attribute entryType, and then sort by
all the objects that use entryType by their typeField attribute, use the following:
CustomEntitiesExt:
defaultSort:
- entryType
- typeField
Configuring the element resource file

The element resource file contains implementation code used to manipulate an element resource.
The name of this file is <elementResource>Resource.gs. The file is in the
gw.rest.ext.cc.<api>.<ancestor>.<resource> package. For example, when generating endpoints for a
CustomEntity_Ext data model entity in the Claim API whose ancestor is Claim:
• The element file is named CustomEntityExtResource.gs.
• It is in the gw.rest.ext.cc.claim.v1.claims.customentityext package.
You must modify the following getters and methods in the class in the following ways.
The init method

The init method initializes a new instance of this resource, and ensures that this element resource is a child of the
element of its parent resource.
In most cases, the example code provided is sufficient, and requires only uncommenting the method code and
defining the parent foreign key. For example, your child element and its resource uses claim as its parent resource.
The uncommented method code looks like this:
override function init(parent : CustomEntityExtResource, elementId : String) {
super.init(parent, elementId)
validateParentChildConsistency(this.Parent.Parent.Element, this.Element.Claim)
}
The delete method

The delete method deletes the resource, and can provide an exception to the delete method from a business
standpoint.
In most cases, the example code provided is sufficient, and requires only uncommenting the method code. For
example, the uncommented method code looks like this:
override function delete() {
this.Element.remove()
}
The canEditException getter

The CanEditException getter determines whether the resource is editable from a business standpoint. If the
resource is editable, the getter returns null. If the resource is uneditable, the getter returns a CanEditException.
For example, suppose the resource has an ExpirationDate field and edits can be made only before the expiration
date.
• If today's date is on or before the ExpirationDate, the getter returns null.
• If today's date is after the ExpirationDate, the getter returns a
LocalizedExceptionUtil.operationNotCurrentlyAllowedException
The following code illustrates this:
override property get CanEditException() : RestRequestException {
var today = Calendar.getInstance().getTime();
if (this.CustomEntity_Ext.ExpirationDate > today)
return null
else
return LocalizedExceptionUtil.operationNotCurrentlyAllowedException
}
In most cases, you do not need constraints on editing the resource based on its business state, and the getter always
returns null. For example:
override property get CanEditException() : RestRequestException
{
return null
}
Note: The purpose of this getter is to prevent edits based solely on the business state of the resource. It
is not intended to control authorization. For more information, see “Configuring authorization for
The canDeleteException getter

The CanDeleteException getter determines whether the resource can be deleted from a business standpoint. If the
resource can be deleted, the getter returns null. If the resource cannot be deleted, the getter returns a
CanEditException.
For example, suppose the resource has an ExpirationDate field and can be deleted only before the expiration date.
LocalizedExceptionUtil.operationNotCurrentlyAllowedException.
override property get CanDeleteException() : RestRequestException {
return null
else
return LocalizedExceptionUtil.operationNotCurrentlyAllowedException()
}
In most cases, you do not need constraints on viewing the resource based on its business state, and the getter always
override property get CanViewException() : RestRequestException {
return null
}
Note: The purpose of this getter is to prevent edits based solely on the business state of the resource. It
is not intended to control authorization. For more information, see “Configuring authorization for
The canViewException getter
The CanViewException getter determines whether the resource is viewable from a business standpoint. If the
resource is viewable, the getter returns null. If the resource is not viewable, the getter returns a CanViewException.
For example, suppose the resource has an ExpirationDate field and can be viewed only before the expiration date.
LocalizedExceptionUtil.operationNotCurrentlyAllowedException.

return null
else
return LocalizedExceptionUtil.operationNotCurrentlyAllowedException()
}
return null
}
Note:
The purpose of this getter is to prevent views based solely on the business state of the resource. It is
not intended to control authorization. For more information, see “Configuring authorization for
Configuring the collection resource file

The collection resource file contains implementation code used to manipulate a collection resource.
The name of this file is <collectionResource>Resource.gs. The file is located in the
gw.rest.ext.cc.<api>.<ancestor>.<resource> package. For example, when generating endpoints for a
CustomEntities_Ext data model entity in the Claim API whose ancestor is Claim:
• The element file is named CustomEntitiesExtResource.gs.
• It is in the gw.rest.ext.cc.claim.v1.claims.customentityext package.
You must modify the following getters and methods in the class in the following ways.
The loadValues method (stream-backed collections only)
The loadValues method converts the collection resource array into a Java stream object, and populates the response
payload with the stream-backed collections
For example, suppose the parent of CustomEntitities_Ext has an array of CustomEntitities_Ext(). This
method returns that array converted into a stream. The following code illustrates this:
protected override function loadValues() : Stream<Object> {
return this.Parent.Element.getCustomEntities_Ext().stream()
If the parent does not have an array of the custom entity, then you must write Gosu code to construct an array or list
manually and then convert it into a stream.
Note: The purpose of this method is to construct the set of available elements as determined by the
authorization layer. It is not intended to control authorization itself. For more information on
controlling authorization, see “Configuring authorization for generated endpoints” on page 353.
The buildBaseQuery method (query-backed collections only)
The buildBaseQuery method creates a Gosu query that returns the collection resource related to the parent resource.
For example, suppose the parent of CustomEntity_Ext is Account. This method needs to return all
CustomEntity_Ext instance associated with the relevant account. following code illustrates this:
protected override function buildBaseQuery() : IQueryBeanResult<CustomEntity_Ext> {

return Query.make(entity.CustomEntity_Ext)
.compare(CustomEntity_Ext#Account, Relop.Equals, this.Parent.Element)
.select()
Note: The purpose of this method is to construct the set of available elements as determined by the
authorization layer. It is not intended to control authorization itself. For more information on
controlling authorization, see “Configuring authorization for generated endpoints” on page 353.
The canViewException getter
The CanViewException getter determines whether the collection resource is viewable from a business standpoint. If
the collection resource is viewable, the getter returns null. If the collection resource is not viewable, the getter
returns a CanViewException.
return null
}
If there are no constraints on editing the resource based on its business state, then the getter always returns null.
Note: The purpose of this getter is to prevent creation based solely on the business state of the
resource. It is not intended to control authorization. For more information, see “Configuring
authorization for generated endpoints” on page 353.
The canCreateException getter
The CanCreateException getter determines whether the collection resource can be created from a business
standpoint. If the collection resource is createable, the getter returns null. If the collection resource is not createable,
the getter returns a CanCreateException.
If there are no constraints on creating the resource based on any business state, then the getter always returns null.
Note: The purpose of this getter is to prevent creation based solely on the business state of the
resource. It is not intended to control authorization. For more information, see “Configuring
authorization for generated endpoints” on page 353.
The createMinimalChildElement method
The createMinimalChildElement method is used for POSTs on the collection resource. It creates a new instance of
the entity and attaches it to its parent.
In most cases, the example code as shown below is sufficient. However, if there is additional initialization logic, it
can be defined here.
override function createMinimalChildElement(attributes : DataAttributes) : CustomEntity_Ext {
var customEntity_Ext = new CustomEntity_Ext()
customEntity_Ext.Account = this.Parent.Element
return customEntity_Ext

In addition to the glue and impl files, you must also configure the resource definition files and the authorization
files.
on page 353.
page 353.

chapter 54
Configuring authorization for

generated endpoints
This topic discusses how to configure the authorization files. They are the files highlighted in the following
on page 353.
on page 353.
Configuring authorization for generated endpoints 421

Configuring endpoint access for generated endpoints

Endpoint access defines the aspects of an endpoint's behaviors that are available to a caller. This includes:
• What endpoints are available to the caller?
• What operations can a caller call on the available endpoint?
• What fields can the caller specify in a request payload or get in a response payload?
For more information on the general behavior of endpoint access, see Cloud API Authentication Guide .
When running the Rest Endpoint Generator, several prompts pertain to endpoint access. This includes:
• Which roles can access the GET collection and GET element endpoint?
• Which roles can access the POST collection endpoint?
• Which roles can access the PATCH element endpoint?
• Which roles can access the DELETE element endpoint?
Based on the responses, the Rest Endpoint Generator adds code to the corresponding role.yaml files. Places where
additional coding may be needed are flagged with the following comment:
Code generated in role.yaml files

Providing access to all operations
If you specify that a given role has GET, POST, PATCH, and DELETE access to a generated endpoint, the REST
Endpoint Generator adds the following code to the associated role.yaml file:
- endpoint: /<path>/<customEndpointCollection>
# TODO RestEndpointGenerator : Adjust the permissions appropriately
methods:
- GET
- POST
- endpoint: "<path>/<customEndpointCollection>/*"
methods:
- GET
- DELETE
- PATCH
The first block grants the ability to retrieve a collection and the ability to create a resource.
The second block grants the ability to retrieve an element, to modify an element, and to delete an element. (A single
* wildcard indicates access is provided for anything one level below the current endpoint level.)
For example, suppose you generated endpoints for the CustomEntity_Ext data model entity and added GET, POST,
PATCH, and DELETE access for these endpoints to the Manager role. The Rest Endpoint Generator would add the
following lines to the Manager.role.yaml file:
- endpoint: /account/v1/accounts/custom-entities-ext
methods:
- GET
- POST
- endpoint: "/account/v1/accounts/custom-entities-ext/*"
methods:
- GET
- DELETE
- PATCH
422 chapter 54: Configuring authorization for generated endpoints

The first block grants the ability to retrieve a collection of CustomEntities_Ext and the ability to create a
CustomEntity_Ext.
The second block grants the ability to retrieve a specific CustomEntity_Ext, to modify a CustomEntity_Ext, and
to delete a CustomEntity_Ext.
Limiting access to only some operations

If a given role can GET but not POST the new resource, the POST operation is omitted from the first block.
If a given role can GET but not PATCH (or DELETE) the new resource, the PATCH (or DELETE) operation is
omitted from the second block.
If a given role cannot GET the new resource, then both blocks are omitted. (In order to POST, PATCH, or DELETE
a resource, the role must also have the ability to GET it.)
Configuring code in role.yaml files

If you specified roles in response to the REST endpoint generator prompts, then the endpoint access code generated
by the REST Endpoint Generator is likely to be usable as is. However, there may be cases where additional
configuration is required. For example:
• Guidewire recommends removing the TODO RestEndpointGenerator comments.
• An insurer may want to add additional field-level access in the accessibleFields section.
For more information on how to configure role.yaml files, see Cloud API Authentication Guide.
Configuring resource access for generated endpoints

Resource access defines, for a given type of resource, which instances of that resource type the caller can access. For
example, for a given caller, endpoint access might grant access to a GET /policies endpoint. But this does not
necessarily mean the caller can access every policy in the system. Resource access can limit which specific policies
that caller can view.
For more information on the general behavior of resource access, see the Cloud API Authentication Guide.
When running the Rest Endpoint Generator, there are no prompts that pertain to resource access. The Rest Endpoint
Generator generates resource access code in the same way for every set of generated endpoints. At the very least, the
code requires review. In some cases, the code may also require additional configuration. The places where coding
requires review and additional completion is flagged with the following comment:
Code generated in access.yaml files

Every resource access strategy is defined in multiple files. In the base configuration, all of the files for a given
resource access strategy start with the same name.
Broadly speaking, there are two types of access files: core and extension.
A core access file is an access file that defines one or more base configuration resource access strategies. Core
access files either have core in the name, or are located in a package with core in the path.
WARNING Do not modify any core access files. Modifying these files can result in certain sets of
callers being unable to execute API calls.
An extension access file is an access file that provides a location for extensions to base configuration resource access
strategy behavior. Extension access files either have ext in the name, or are located in a package with ext in the
path.
Code generated by the REST Endpoint Generator is placed in extension access files. The specific code added to each
file depends on the associated type of caller.
Generated resource access code for internal users

The extension access file for internal users is named internal_ext-1.0.access.yaml.
The REST Endpoint Generator assumes that an internal user can access a given instance of the custom resource if
the internal user can also access the resource's parent. Therefore, the filters for all operations are set to __inherit.
Stream-based collections
If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a stream, the following is
added to the internal user resource access extension file:
resources:
CustomEntitiesExt:
# TODO RestEndpointGenerator : Update the default generated access here
permissions:
view: __inherit
create: __inherit
CustomEntityExt:
permissions:
view: __inherit
edit: __inherit
delete: __inherit
Query-based collections
If you generate endpoints for a CustomEntity_Ext entity, and the entity is backed by a query, the following is added
to the internal user resource access extension file:
resources:
CustomEntitiesExt:
permissions:
view: __inherit
create: __inherit
filter: __noFilter
CustomEntityExt:
permissions:
view: __inherit
edit: __inherit
delete: __inherit
Note that, for query-backed collections, there is an additional "filter: __noFilter" line of code in the collections
section. This line is needed to determine appropriate view permissions for query-backed collections.
• This line of code does not exist for stream-backed collections because stream-backed collections load the entire
collection contents into memory at one time. Cloud API can simply iterate over the entire collection using the
specified view permission to determine which items in the stream can be viewed.
• This line of code does exist for query-backed collections because query-backed collections do not load the
entire collection into memory at one time. Instead, the collection is loaded one page at a time. Additional logic is
required to identify the items in the collection that can be viewed. This is specified by the additional filter.
In most business circumstances, the filter can be set to __noFilter, which specifies no additional filter logic is
needed. This is acceptable because, in most cases, a child object can be viewed if the parent object can be viewed.
Generated resource access code for external users

The extension access file for external users is named accountholder_ext-1.0.access.yaml.
The REST Endpoint Generator does not make any assumptions about when an external user caller can access a
given instance of the custom resource. Therefore, the filters for all operations are declared, but they are not set to
any values.
added to the external user resource access extension file:
resources:
CustomEntitiesExt:
permissions:
view: "TODO RestEndpointGenerator"
create: "TODO RestEndpointGenerator"
CustomEntityExt:
permissions:
edit: "TODO RestEndpointGenerator"
delete: "TODO RestEndpointGenerator"
resources:
CustomEntitiesExt:
permissions:
filter: "TODO RestEndpointGenerator"
CustomEntityExt:
permissions:
Note that, for query-backed collections, there is an additional "filter: TODO..." line of code in the collections
For more information on how to configure resource access files, see Cloud API Authentication Guide.
Generated resource access code for services

The extension access file for internal users is named service_ext-1.0.access.yaml.
The REST Endpoint Generator assumes that services are not restricted by resource access. Therefore, the filters for
all operations are set to true.
added to the service resource access extension file:
resources:
CustomEntitiesExt:
permissions:
view: true
create: true
CustomEntityExt:
permissions:

view: true
edit: true
delete: true
resources:
CustomEntitiesExt:
permissions:
view: true
create: true
filter: __noFilter
CustomEntityExt:
permissions:
view: true
edit: true
delete: true
Note that, for query-backed collections, there is an additional "filter: __noFilter" line of code in the collections
If services are not restricted by resource access, then no additional filter logic is needed. The filter: __noFilter
line of code specifies this.
Generated resource access code for special use cases

There are two resource access strategies used for special cases.
• Unauthenticated user resource access is used for unauthenticated users. This access is defined in
unauthenticated_ext-1.0.access.yaml.
• Default resource access is used for callers who have been authenticated but specify no resource access strategy
with the call. This access is defined in default_ext-1.0.access.yaml.
The REST Endpoint Generator does not make any assumptions about when a caller using these resource access
strategies can access a given instance of the custom resource. Therefore, the filters for all operations are declared,
but they are not set to any values.
added to the unauthorized access extension file:
resources:
CustomEntitiesExt:
permissions:
CustomEntityExt:
permissions:

to the unauthorized access extension file:
resources:
CustomEntitiesExt:
permissions:
filter: __noFilter
CustomEntityExt:
permissions:
Note that, as is the case for the other caller types, query-backed collections have an additional "filter:" line of
code in the collections section.
Configuring generated resource access code

Depending on the business needed, the following resource access configuration may be required:
• The default resource access for internal users is "you can access the custom entity if you can access its parent." If
this is not appropriate or sufficient, you must configure the internal resource strategy extension file.
• The default resource access for services is "you can access all custom entities." If this is not appropriate or
sufficient, you must configure the service resource strategy extension file.
• There is no default resource access for external users, unauthenticated users, or callers with default access. If
your endpoints support any of these types of callers, you must configure the corresponding resource strategy
extension file.
For more information on how to configure resource access files, see Cloud API Authentication Guide
Configuring generated resource access code

Depending on the business needed, the following resource access configuration may be required:
• The default resource access for internal users is "you can access the custom entity if you can access its parent." If
this is not appropriate or sufficient, you must configure the internal resource strategy extension file.
• The default resource access for services is "you can access all custom entities." If this is not appropriate or
sufficient, you must configure the service resource strategy extension file.
• There is no default resource access for external users, unauthenticated users, or callers with default access. If
your endpoints support any of these types of callers, you must configure the corresponding resource strategy
extension file.
For more information on how to configure resource access files, see the Cloud API Authentication Guide.

Once you have run the REST endpoint generator and configured the resource definition files, the glue and impl
Gosu files, and the authorization files, the configuration of the new CRUD endpoints is complete.


chapter 55
Generating endpoints for ClaimCenter

Policy graph entities
In the Claims API, generating endpoints that are descendants of the resource Policy differ from the standard REST
endpoint generator script behavior as well as the glue and impl file configuration.
Creating Policy descendant endpoints

Policies created during the First Notice of Loss (FNOL) process exist under two paths: the verified policy endpoints
confirmed by the PAS that use Policy as the parent resource— /claims/{claimId}/policy ; /claims/
{claimId}/policy/vehicle-risk-units — and unverified policy endpoints not confirmed by the PAS that use
UnverifiedPolicies as a root resource-- /unverified-policies/{policyId}; /unverified-policies/
{policyId}/vehicle-risk-units. Verified policies are read-only and allow only GET operations, while
unverified policies are editable and permit GET/PATCH/POST operations, such as /coverages:
Policy as a parent to the custom resource

The entity must use Policy or a descendant of Policy as its parent, regardless of how distant the ancestor. Endpoints
that use Policy or descendant of policy employ the ClaimCenter-specific behavior and configuration.
REST endpoint generator variances for Policy endpoints

• All descendants of Policy use query-backed retrieval. You cannot select a Java stream to retrieve collections.
• Policy entities always use the claim integration graph.
Therefore, the REST endpoint generator does not prompt for query or stream-backed resources, or adding the entity
to an integration graph.
Configuring variances for glue and impl classes for Policy endpoints
Policy endpoints create and change the same series of files as standard endpoints but vary in logic for how the
endpoint interacts with the application.
• The apiconfig file generates extra entities for the verified and unverified policy resources. For example,
CustomPolicyEntitiesExt:
resource: gw.rest.ext.cc.claim.v1.claims.policy.custompentityext.CustomPolicyEntitiesExtResource
…
Generating endpoints for ClaimCenter Policy graph entities 429

UnverifiedCustomPolicyEntitiesExt:
resource: gw.rest.ext.cc.claim.v1.claims.policy.custompentityext.UnverifiedCustomPoliciesEntitiesExtResource
mapper: CustomPolicyEntityExt
updater: CustomPolicyEntityExt
• There are four “impl” files that define implementation details for the verified and unverified policy resources.
◦ Two <collection>Resource.gs file Gosu files that defines required behaviors for working with collections for
verified and unverified policy resources. For example:
▪ <collectionResource>Resource.gs
▪ Unverified<collectionResource>Resource.gs
◦ Two <element>Resource.gs file Gosu files that define required behaviors for working with elements for
verified and unverified policy resource. For example:
▪ <elementResource>Resource.gs
▪ Unverified<elementResource>Resource.gs
See respective sections below for variances and coding details
Configuring variances for the apiconfig file

The REST endpoint generator automatically changes the apiconfig file to map Policy element and collection
resources for both verified and unverified policy resources to the respective Resource Gosu.
Guidewire recommends a default sort order for your verified and unverified collection resources to supply a
consistent, deterministic response payload. Decide the object by which the response payload orders its collection by
defining the default sort order. For example:
CustomPEntitiesExt:
resource: gw.rest.ext.cc.claim.v1.claims.policy.custompentityext.CustomPEntitiesExtResource
defaultSort:
- customDescription
…
UnverifiedCustomPEntitiesExt:
resource: gw.rest.ext.cc.claim.v1.claims.policy.custompentityext.UnverifiedCustomPEntitiesExtResource
mapper: CustomPEntityExt
updater: CustomPEntityExt
defaultSort:
- customDescription
Configuring variance for Policy resource files

Policy endpoint impl files for verified and unverified policies variances are as follows:
Verified resource files
• Verified and unverified element resources do not include delete methods. You cannot delete verified policies or
child object on verified policies, and Guidewire does not offer deletion of unverified policies at this time.
Unverified resource files
• Unverified Policy element resource files generate an additional operation
finishCreate(data,batchUpdateMap) to reserve Ids for additional beans created by the Policy resource. See
The finish create operation for more information.
• Unverified Policy collection resource files generate an additional property getter get Policy(): Policy to
connect the path from policy descendants to the Policy resource. See the policy getter for mor information.
The policy getter

In the Unverified<collectionResource>Resource.gs file, the policy getter connects the path from the policy
descendant to the policy.
For example, if your endpoint has a Foreign Key to of Grandchild_Ext, which then has a foreign key Child_Ext,
to which has a foreign key to Policy with this.Parent.Element.Policy.
private property get Policy() : Policy {
return (this.Parent.Element.Policy)
430 chapter 55: Generating endpoints for ClaimCenter Policy graph entities
}
}
The finishCreate operation
In the Unverified<elementResource>Resource.gs, the finishCreate operation reserves Ids for any additional
objects resulting from the creation of the Policy endpoint.
Creating an unverified policy requires composite requests to execute subsrequests for claim and policy creation.
Composite request reserve Id values so that these Ids can be provided in subresponses and committed to the
database. For example, a subrequest of POST /claims returns a response for with a reserved Id.
However, the composite API does not reserve Ids for inline objects create in composite response payloads. For
example, the framework API assigns an Id for the /unverified-policies/policyId/
vehicleRiskUnitsendpoint, but not the inline child object vehicle. Subrequests rely on the finishCreate
operation to reserve Ids for an inline object.
If the updater or schema files for your risk unit endpoint contain custom inline objects of which you want to reserve
an Id, implement the finishCreate operation.
For example, your risk unit schema or mapper contains the inline object framing, and you want to reserve an Id
from the framing object in response payloads.
var riskUnit = this.Element
reserveIdsIfNecessary({riskUnit.framing})
}
Creating custom risk units

You can manage subtypes of risk units (which inherently must use Policy as a parent resource) with an endpoint.
Generating custom risk units differs from standard the REST endpoint generator script behavior as well as its glue
and impl file configuration.
Risk unit criteria

The REST endpoint generator can create a custom subtype for only risk units. This includes the following:
• The EntityType must use subtype.
• The entity must use RiskUnit as its subtype.
• The entity must use Policy or a descendant of Policy as its parent, regardless of how distant the ancestor.
Endpoints that use Policy or descendant of policy employ the following ClaimCenter-specific behavior and
configuration.
REST endpoint generator variances for custom risk units

The following section details the abbreviated REST endpoint generator prompts when creating custom risk units.
After the first prompt for entering your risk unit entity name ( Which data model entity would you like to
generate endpoints for?), the REST endpoint generator already understands the following:
• Risk units inherently belong on the Claim API.
• Policy entities always use the claim integration graph
Therefore, the REST endpoint generator does not prompt for the API name, if the entity is at the root of the path, or
if the endpoint belongs to an integration graph.
Note: Inputting anything other than Policy or a descendant of Policy as a Parent resource presents an
error during the script.
Configuring variances for glue and impl classes for risk units
Policy endpoints create and change the same series of files as standard endpoints but vary in logic for how the
endpoint interacts with the application.
Risk units create and change the same series of files as standard endpoints but vary in logic for how the endpoint
interacts with the application.
• The risk unit schema, mapper, and updater files generate additional attributes of RUNumber, Description, and
PolicySystemId. These attributes match the default schema for risk unit entities.
• The risk unit schema, mapper, and updater files can include custom inline damageables for the policy coverage.
See Inline damageable for details.
• The modified apiconfig file generates extra entities for the verified and unverified policy resources.
• The modified apiconfig file for the Risk unit collection resource includes a default ascending sort by RUNumber:
UnverifiedCRiskUnits2Ext:
resource: gw.rest.ext.cc.claim.v1.claims.policy.criskunit2ext.UnverifiedCRiskUnits2ExtResource
mapper: CRiskUnit2Ext
updater: CRiskUnit2Ext
defaultSort:
- RUNumber
The default sort can be modified or added to as other endpoints.

• There are four “impl” files that define implementation details for the verified and unverified Risk unit resources.
◦ Two <collection>Resource.gs file Gosu files that defines required behaviors for working with collections for
verified and unverified policy resources. For example:
▪ <collectionResource>Resource.gs
▪ Unverified<collectionResource>Resource.gs
◦ Two <element>Resource.gs file Gosu files that define required behaviors for working with elements for
verified and unverified policy resource. For example:
▪ <elementResource>Resource.gs
▪ Unverified<elementResource>Resource.gs
See respective sections below for variances and coding details.
Configuring variances for risk unit resource files

Risk unit endpoint impl files for verified and unverified policies variances are as follows:
Verified and unverified resource files
• Verified and unverified risk unit element and collection resources do not include delete methods. You cannot
delete verified risk units or child objects of a Risk unit on verified policies, and Guidewire does not offer deletion
of unverified risk units at this time.
Verified resource files
• Verified element resources do not include CanViewException as it inherently returns null.
• Verified collection resources do not include CanViewException as it inherently returns null.
Unverified resource files
• Unverified element resource files generate an additional operation finishCreate(data,batchUpdateMap) to
reserve Ids for additional beans created by the Policy resource.
• Unverified element resources do not include CanViewException, CanEditExcpetion, and CanDeleteException
methods as they inherently return null.
• Unverified collection resources do not include CanViewException and CanCreateException as it inherently
returns null.
• Unverified risk unit collection resource files generate an additional property getter get Policy(): Policy to
connect the path from policy descendants to the Policy resource.
• Unverified Risk unit collection resource generates the createMinimalChildElement. However, if the risk unit
does not directly descend from Policy, you must set the parent foreign key to be set to the earliest parent (such as
for using Policy as the immediate parent resource riskUnit.{{ChildOfPolicyFK}} =
this.Parent.Element).
The policy getter

In the Unverified<collectionResource>Resource.gs file, the policy getter connects the path from the policy
descendant to the policy.
For example, if your endpoint has a foreign key to of Grandchild_Ext, which then has a foreign key Child_Ext, to
which has a foreign key to Policy with this.Parent.Element.Policy.
private property get Policy() : Policy {
return this.Parent.Element.Policy
}
}
The finishCreate operation

In the Unverified<elementResource>Resource.gs ,the finishCreate operation reserves Ids for any additional
objects resulting from the creation of the Policy endpoint.
Creating an unverified policy requires composite requests to execute subsrequests for claim and policy creation.
Composite request reserve Id values so that these Ids can be provided in subresponses and committed to the
database. For example, a subrequest of POST /claims returns a response for with a reserved Id.
However, the composite API does not reserve Ids for inline objects create in composite response payloads. For
example, the framework API assigns an Id for the /unverified-policies/policyId/vehicleRiskUnits
endpoint, but not the inline child object vehicle. Subrequests rely on the finishCreate operation to reserve Ids for
an inline object.
If the updater or schema files for your risk unit endpoint contain custom inline objects of which you want to reserve
an Id, implement the finishCreate operation.
For example, your risk unit schema or mapper contains the inline object framing, and you want to reserve an Id
from the framing object in response payloads.
var riskUnit = this.Element
reserveIdsIfNecessary({riskUnit.framing})
}
Inline damageables
In the same way VehicleRiskUnits schema uses Vehicle as an inline variable to determine a damageable, you can
associate the risk unit with a custom entity to represent the covered risk unit damageable.
Guidewire recommends extending the custom damageable entity to determine whether it belongs to the policy.
Guidewire also recommends including on the entity a policySystemId attribute to populate when integrating with the
PAS. See examples below.
Inline damageables in the schema file

The properties object defines values generated by the generator and customer specific values found on the custom
policy risk unit. policyCustomDamageable provides other customer specific-values found on the custom
damageable.
The following code illustrates inline damageables in the schema file:
claim_ext-1.0.schema.json
"CustomPolicyEntityExt": {
"title": "Custom policy entity ext",
"description": "Custom policy entity ext"
"type": "object",
"properties": {
"customDamageable_Ext": {
"title": "Custom damageable",
"description": "The custom Damageable that is covered",
"$ref": "#/definitions/custom Damageable"
}
}
}
...
"customDamageableExt": {
"title": "customdamageableext",
"description": "Custom damageable ext",
"type": "object",
"properties": {
"displayName": {
"title": "Display name",
"description": "The formatted name of this custom damageable",
"type": "string",
"readOnly": true
},
"id": {
"title": "ID",
"type": "string"
},
"policyCustomDamageable": {
"title": "Policy custom damageable",
"description": "A `true` value indicates that this custom damageable is part of
the claim's policy and cannot be edited directly",
"type": "boolean",
"readOnly": true
},
"policySystemId": {
"title": "Policy system ID",
"description": "The unique identifier of this element within the policy system",
"type": "string"
},
}
},
Inline damageables in the mapping file

policy risk unit. policyCustomDamageable supplies other customer specific-values found on the custom
damageable.
The following code illustrates inline damageables in the mapping file:
claim_ext-1.0.mapping.json
"schemaDefinition": "CustomPolicyEntityExt",
"root": "entity.CustomPolicyEntity_Ext",
"properties": {
"fooBar_Ext": {
"path": "FooBarRiskUnit_Ext.FooBar_Ext",
"mapper": "#/mappers/FooBarExt"
}
}
}
...
"customDamageableExt": {
"schemaDefinition": "Custom damageable ext",
"root": "entity.customDamageable_Ext",
"properties": {
"displayName": {
"path": "CustomDamageable_Ext.RestV1_SafeDisplayName"
},
"id": {
"path": " customDamageable_Ext.RestId"
},
"policyCustomDamageable": {
"path": "customDamageable_Ext.PolicyCustomDamageable_Ext"
},
"policySystemId": {
"path": "customDamageable_Ext.PolicySystemId"
},
}
},
Inline damageables in the updater file

policy risk unit. policyCustomDamageable supplies other customer specific-values found on the custom
damageable.
The following code illustrates inline damageables in the updater file:
claim_ext-1.0.updater.json
"schemaDefinition": "CustomPolicyEntityExt",
"root": "entity.CustomPolicyEntity_Ext",
"properties": {
"CustomDamageable_Ext ": {
"path": "customPolicyEntity_Ext.PolicyCustomDamageable_Ext ",
"create": "{var fooBar = new Policy CustomDamageable_Ext (CustomDamageable_Ext); customDamageable.
policyCustomDamageable_Ext = true; return CustomDamageable}",
"updaterRef": "#/updaters/customDamageableExt
}
}
},
...
"CustomDamageableExt": {
"schemaDefinition": "CustomDamageableExt ",
"root": "entity. CustomDamageable_Ext ",
"properties": {
}
},

chapter 56
Additional considerations for

generated endpoints
This topic covers special use cases of the REST endpoint generator and consideration for those use cases.
Integration graphs
An integration graph is a data model graph used by Guidewire App Events. It defines a set of business information
to be sent to an external application as part of outbound integrations. For example, the Claim graph defines what
information to send about a claim. For more information on integration graphs, see the App Events Guide.
When you generate endpoints for a custom entity, you can also add the custom resource to an integration graph if the
resource has a parent resource and that parent resource belongs to the integration graph. To add the custom resource
to the graph, answer the final prompt ("Should <CustomEntity> be added to an integration graph?") with "y".
• If the entity is effective-dated, the information is added to the policy period graph.
• If the entity is not effective-dated, an additional prompt asks for the name of the graph to add the entity to.
When a custom entity is added to an integration graph, the REST endpoint generator modifies the following files:
• The <graphName>_graph_ext-1.0.schema.json file
• The <graphName>_graph_ext-1.0.mapping.json file
• The shared_ext-1.0.apiconfig.yaml file
You do not need to configure the graph schema file. But, configurations are required in the graph mapper file and the
apiconfig.yaml file.
The graph schema file

The graph schema file defines the structure of the integration graph. When you specify that you want to add a
custom resource to a given graph, the REST endpoint generator adds code to the corresponding
<graphName>_graph_ext-1.0.schema.json file.
For example, suppose you generated endpoints for the CustomEntity_Ext data model entity and added the
corresponding resource to the Claim graph. The claim_graph_ext-1.0.schema.json file has the following code
added (shown in bold):
{
"$schema": "http://json-schema.org/draft-07/schema#",
"x-gw-combine": [
"ext.claim.v1.claim_combined_ext-1.0",
Additional considerations for generated endpoints 437

"gw.content.cc.claim.v1.claim_graph_content-1.0"
],
"definitions": {
"Claim": {
"properties": {
"customEntitiesExt": {
"title": "Custom entities ext",
"description": "The collection of custom entities ext on this claim",
"type": "array",
"items": {
"$ref": "#/definitions/CustomEntityExt"
}
}
}
}
}
}
Typically, the graph schema file does not require configuration.
The graph mapper file

The graph mapper file defines how information is written to the properties in an integration graph. When you
specify that you want to add a custom resource to a given graph, the REST endpoint generator adds code to the
corresponding <graphName>_graph_ext-1.0.mapping.json file.
corresponding resource to the Claim graph. The claim_graph_ext-1.0.mapping.json file has the following code
{
"schemaName": "ext.claim.v1.claim_graph_ext-1.0",
"combine": [
],
"mappers": {
"Claim": {
"schemaDefinition": "Claim",
"root": "entity.Claim",
"properties": {
"path": "TODO RestEndpointGenerator provide a collection
of CustomEntities_Ext",
"mapper": "#/mappers/CustomEntityExt"
}
}
}
}
}
You must configure the file by specifying the path for custom entity collection properties. This is typically set to the
corresponding array on the parent data model entity.
Following on from the previous example, the path attribute in claim_graph_ext-1.0.mapping.json file would
need to be set as follows:
{
"schemaName": "ext.claim.v1.claim_graph_ext-1.0",
"combine": [
],
"mappers": {
"Claim": {
"schemaDefinition": "Claim",
"root": "entity.Claim",
"properties": {
"path": "Claim.CustomEntities_Ext",
"mapper": "#/mappers/CustomEntityExt"
}
}
}
438 chapter 56: Additional considerations for generated endpoints

}
}
The apiconfig mapping

The shared_ext-1.0.apiconfig.yaml maps shared element resource and collection resources to Resource Gosu
file. It also specifies URI mappings for integration graphs. When you specify that you want to add a custom resource
to a graph, the REST endpoint generator adds code to the corresponding shared_ext-1.0.apiconfig.yaml file.
corresponding resource to the Claim graph. The shared_ext-1.0.apiconfig.yaml file has the following code
entityURIMappings:
CustomEntity_Ext:
uri: "${parentUri}/custom-entities-ext/${CustomEntity_Ext.RestId}"
parent: "TODO RestEndpointGenerator link to the parent of CustomEntity_Ext"
You must configure the file by specifying the parent for custom entities. This is typically set to the corresponding
foreign key on the custom data model entity.
Following on from the previous example, the path attribute in the shared_ext-1.0.apiconfig.yaml file would
need to be set as follows:
entityURIMappings:
CustomIEntity_Ext:
uri: "${parentUri}/custom-entities-ext/${CustomEntity_Ext.RestId}"
parent: "CustomEntity_Ext.Claim"
Additional considerations for generated endpoints 439

440 chapter 56: Additional considerations for generated endpoints

CloudAPIGuide BusinessFlows

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CloudAPIGuide BusinessFlows

Uploaded by

Copyright:

Available Formats

Guidewire PolicyCenter™

for Guidewire Cloud

Cloud API Business Flows and

Product Name: Guidewire PolicyCenter for Guidewire Cloud

2 Overview of the system APIs in Cloud API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

3 GETs and response payload structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

The collection-level links section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

4 Refining response payloads using query parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

5 POSTs and request payload structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

PATCHes and arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

8 Reducing the number of calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

9 Composite requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

10 Request inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

11 Batch requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

12 Lost updates and checksums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Tutorial: DELETE a note using checksums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

13 Cloud API headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

16 Managing accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

17 Managing bound policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

21 Policy change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

24 Rewrite and Rewrite New Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

25 Lines of business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

26 Coverables and coverages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Overview of coverages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

29 Exposures, exclusions, and conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

30 Synchronization and deferred validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

31 Policy contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

32 Policy locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

33 Working with product definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

34 PATCHing jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

36 Policy and job search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

37 Out-of-sequence conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

39 Underwriting issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

43 Users and groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

45 Producer codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

47 Obfuscating Personally Identifiable Information (PII). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

48 Localizing schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

49 APIs for lines of business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

51 Running the REST endpoint generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

52 Configuring the resource definition files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Configuring the updater file for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407

53 Configuring glue and impl classes for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

54 Configuring authorization for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

55 Generating endpoints for ClaimCenter Policy graph entities . . . . . . . . . . . . . . . . . . . . . . . . . . 429

56 Additional considerations for generated endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

For assistance, visit the Guidewire Community.

Consuming Cloud API

REST API fundamentals in Cloud API

The InsuranceSuite Cloud API

Making system API calls

REST API fundamentals in Cloud API 19

System APIs and InsuranceSuite logic

20 chapter 1: REST API fundamentals in Cloud API

Note that a field can store:

REST API fundamentals in Cloud API 21

Inline and included resources

Child resources can be declared either as inline resources or included resources.

Operation mapping to elements and collections

Operation On endpoint... Does the following...

PATCH /activities/{activityId} Updates information on the specified activity

22 chapter 1: REST API fundamentals in Cloud API

Contrasting endpoints and operations

The PUT operation