Designing a request payload

Request payload structure

The basic structure for a request payload that creates a single resource is:

{
  "data": {
    "attributes": {
      <field/value pairs are specified here>
    }
  }
}

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

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

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

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

Determining the minimum creation criteria

For most types of business objects, there are a set of fields that you must specify when creating that type of object. For example:

  • To create an activity, the only required field is activityPattern.
  • To create a document, the required fields are name, status, and type.
  • To create a note, the only required field is body.

It is typically not possible to determine the minimum required fields from the API definition. This is because the minimum required fields are often enforced not by Cloud API but rather by PolicyCenter. The easiest way to determine the minimum required fields is to refer to this documentation. For example:

  • The minimum required fields for activities are documented in Activities.
  • The minimum required fields for activities are documented in Documents.
  • The minimum required fields for activities are documented in Notes.

The documentation also provides examples for how to create various types of business objects and information on any requirements or behaviors unique to that type of object.

Specifying scalar values

Scalar values follow these patterns:

Field value type Pattern Example Notes
String "fieldName" : "value"

"firstName" : "Ray",

"id": "demo_date:12"

ids are considered strings.
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": "2020-04-09"

Expressed using the format

YYYY-MM-DD

Datetime "fieldName" : "value" "createdDate": "2020-04-09T18:24:57.​256Z"

Expressed using the format

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.

For scalars, the formats for values are the same for request payloads and response payloads. For a given field, you can use its format in a response payload as a model for how to build a request payload.

ids

ID values are assigned by PolicyCenter. Therefore, you cannot specify an id for an object that is being created. However, you can specify ids when identifying an existing object that the new object is related to.

Specifying compound values

InsuranceSuite includes several datatypes where multiple values are stored as a unit. This includes the following:

  • Typekey (containing a code and a name)
  • MonetaryAmount and CurrencyAmount (containing a currency and an amount)
  • SpatialPoint (containing a longitude coordinate and a latitude coordinate)
For example, an activity's assignmentStatus property is a typekey. Thus, the response payload for an activity's assignment status has two sub-fields (code and name):
"assignmentStatus": {
  "code": "assigned",
  "name": "Assigned"
}

Typekeys

Typekeys use the following format:

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

For example:

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

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

Monetary amounts

Monetary amounts use the following format:

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

For example:

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

Spatial points

Spatial points use the following format:

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

For example:

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

Setting values and objects to null

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

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

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

"homePhone": null

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

"language": null

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

"transactionAmount": null