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.