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 ClaimCenter. (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 ClaimCenter. (For example, there could be a validation rule in ClaimCenter 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, ClaimCenter 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.",
                  "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": {
               }
          }
}

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

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

IDs

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

Specifying objects in a request payload

The syntax for specifying an object is:

"objectName": {
      "field1": value_or_"value",
      "field2": value_or_"value",
      ...
      }

For example:

"assignedUser": {
      "displayName": "Andy Applegate",
      "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"
}

(Note that in the system APIs, the datatype is referred to as MonetaryAmount. But in ClaimCenter, these values are actually stored using the CurrencyAmount datatype.)

Related objects

For information on how to specify related objects in a request payload, see Request inclusion.

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