Understanding the Graph API

The Graph API includes the following endpoints:

• POST /graph/v1/accounts

• POST /graph/v1/submissions

The POST /graph/v1/accounts endpoint lets you create an account by specifying the entire hierarchy for the account in a single request. This endpoint uses the same schemas as those used by the /account/v1/accounts endpoint and its related endpoints. So, any field available to those schemas is available to the POST /graph/v1/accounts endpoint.

The POST /graph/v1/submissions endpoint lets you create a complete job submission. You specify the entire hierarchy for the submission in a single request. This endpoint uses the same schemas as those used by the Job API endpoints, including any LOB-specific endpoints. So, any field available to those schemas is available to the POST /graph/v1/submissions endpoint.

The responses from these endpoints include the entire hierarchy of the account and submission resources. This complete response provides a consistent and ordered set of information so caller applications know what to expect. It also allows caller applications to more easily pass data back to PolicyCenter if necessary without having to first determine the ordering.

These endpoints are similar to the POST /account/v1/accounts and POST /job/v1/submissions endpoints, but there are some key differences, discussed in the next section.

For more on the /account/v1/accounts endpoint see Creating an account

For more on the /job/v1/submissions endpoint see Submissions

The Graph API endpoints are built from the same code as the Account and Job API endpoints. This means that the Graph API endpoints return the same information and the same properties as the Account and Job API endpoints, including any custom extensions that have been added. But there are several differences.

Streamlined process

The Account and Job APIs have separate endpoints to access the child elements of account and job. The Graph API endpoints do not have separate endpoints for child elements because they're not needed. All account and job information, including all child resources, are included within the requests and responses for the Graph API endpoints. For example, a request to POST /graph/v1/accounts can contain all account information, including child information such as contacts and locations.

Note:

Keep in mind that while POST /graph/v1/submissions creates an entire job and submission, it does not quote or bind the submission.

No pagination

When you run an Account or Job API endpoint, pagination is in place that by default restricts the number of elements returned at once. With the Graph API endpoints, all the account and submission information is included in the POST command response. The Graph API overrides any specified pagination values and returns all elements of each collection.

See The pagination query parameters for more information on pagination.

POST only

The purpose of the Graph API endpoints is to produce an entire account and submission that can be passed along for processing by the caller application. So unlike the Account and Job API endpoints, the Graph API /accounts and /submissions endpoints provide only POST commands. Updates cannot be made that will produce a modified version of the entire account or submission graph response. However, you can use the the Account and Job API endpoints to modify the data that was created with the Graph API endpoints.

The Composite API (Composite requests) provides an endpoint that allows you to string together a series of API requests, passing variables - such as an account ID - returned from one sub-request to another. The sub-requests run in the order specified in the composite request, each sub-request completing before the next begins.

You can use Graph API requests within a Composite API request to create a complete submission. For example, you can call POST /graph/v1/accounts, then POST /graph/v1/submissions as part of a single composite request. If you also want to quote the submission, you can include a call to POST /jobs/v1/{jobId}/quote, passing in the jobId returned from the call to the graph /submissions endpoint. See Example: Creating a policy using the graph endpoints for an example.

If you use the Account and Job API endpoints to create a submission, you need to carefully keep track of the order in which to make the requests, being sure to pass the appropriate IDs from one request to another. One of the biggest advantages to using the Graph API is that the endpoints know how to carry out operations in an order that makes sense.

By default, the Graph API will process the list of children for a given resource based on the alphabetical ordering of the properties defined in the graph schema. For example, if a policy line has children named coverages and locations in the graph schema, the coverages children will be processed first.

In some cases, you may want to change this order, generally to ensure that resources are created before other resources attempt to reference them. For example, the base configuration overrides the ordering so that contacts and locations are both processed before any other entities on the Job schema, so that PolicyContacts and PolicyLocations are created before any LOB resources that may need to refer to them are processed.

You might have a case, such as a custom extension with top-level children that are referenced elsewhere in the graph, where you need to control the processing order. You can do this by adding the graphUpdateOrder extension to the appropriate property in the graph schema file. For example:

...
 "x-gw-extensions": {
   "graphUpdateOrder": 1
 }
...

See Cloud API Developer Guide for information on the graph schema file.

As mentioned earlier, the Graph API POST operations create complete accounts and submissions by carrying out the creation of resources and their children in a logical order. In some cases, you might want to reference one of those resources for use in creating another. Graph API uses the refid property to accomplish this.

For example, you might create a contact that you want to designate as the account holder. You can include a refid on the contact. Then add that same refid to the accountHolder. Graph API will first create the contact, then, using the refid, will add that contact as the account holder when it creates the account. Here’s an example:

{
  "data": {
    "attributes": {
      ...
            "accountHolder": {
                "refid": "newperson"
            },
            "contacts": [
                {
                    "refid": "newperson",
                    "contactSubtype": "Person",
                    "firstName": "August",
                    "lastName": "Joseph",


                    "primaryAddress": {
                        "addressLine1": "2850 S. Delaware St.",
                        "city": "San Mateo",
                        "postalCode": "94403",
                        "state": {
                            "code": "CA"
                        }
                    }
                }
            ],
    ...

In the response, the accountHolder is the contact that was created with that refid:

"accountHolder": {
  "displayName": "August Joseph",
  "id": "pc:120"
},
...
"contacts": [
  {
    ... 
    "displayName": "August Joseph",
    "id": "pc:120",
    ...
],

See Cloud API Business Flows and Configuration Guide for more information on request inclusions.

The Graph API endpoints share certain functionality with other API endpoints in PolicyCenter to take note of.

Sort order

Most of the resources in the graph for accounts and submissions are returned as collections. As with other API endpoints, the response from each Graph API endpoint returns data in the default sort order for each resource. This means that, for example, the /accounts endpoint might return a list of contacts in the response in a different order than they were listed in the request.

Response output

If you call GET /job/v1/jobs, the response by default will include a summary list of each job that is returned. However, if you call GET /job/v1/jobs/{jobID} to retrieve a single job, the response will by default include more details about the specified job than the collection-level command response. The response for all POST operations in the Graph API will by default return the detailed list for all collection items.

Request query parameters

The Graph API endpoints accept the following query parameters.

POST /graph/v1/accounts query parameters

Parameter	Description	More information
fields	As with other endpoints, you can override the default set of returned values by using the fields query parameter.	See The fields query parameter for more information.

POST /graph/v1/submissions query parameters

Parameter	Description	More information
createCoveredLocationForPrimaryLocation	This parameter enables or disables the creation of the default covered location for primary location. Default is true (enabled).	See Default value creation for more on creating default coverages.
createDefaultCoverages	This parameter enables or disables the creation of default coverages. Defaults is true (enabled)	See Default value creation for more on creating default coverages.
deferValidation	In some cases you might want to defer validations, such as availability checks. To defer validations on a submission, set this parameter to true. Default is false.	See Deferring validation for more on deferring validation.
fields	As with other endpoints, you can override the default set of returned values by using the fields query parameter.	See The fields query parameter for more information.

Authorization

As with other Cloud API endpoints, in order to call endpoints in the Graph API the caller must have permission to those endpoints in their role.yaml file and the appropriate access.yaml file.That includes endpoint-level permission (via role.yaml files), resource-level permissions (via the access.yaml files), and field-level permissions (via the role.yaml files).

In addition to the standard endpoint permissions, Graph API permissions also depend on the endpoint-level, resource-level, and field-level permissions for the corresponding endpoints within the Account and Job APIs. These permissions are applied to the creation during the POST, and are also used to filter what is returned on the response. Here are some examples.

Creation Authorization

Every graph schema property maps to an Account or Job API endpoint. For example, contacts on the Account maps to /account/v1/accounts/{accountId}/contacts. Adding an element to the contacts array in the request requires exactly the same permissions as a POST to that Account API endpoint would require: if the POST to the Account API would fail, the POST to the Graph API will fail the same way. This applies to field-level edits as well: if you can't edit a field in the Account API, you can't include that field in a Graph API request.

Response

Response rules are similar to the creation rules. If you can't view the response from the /account/v1/accounts/{accountId}/contacts endpoint in the Account API, the contacts property won't appear on the /graph/v1/accounts response. Similarly, if you can't view a particular set of contact fields in the Account API, those fields won't appear in the Graph API response either. The Graph API is designed to give callers the same permissions as to the Account and Job APIs.

See Example: Creating a policy using the graph endpoints for complete examples of using the Graph API endpoints.