Overview of POSTs

A POST is a REST API method that creates a resource in PolicyCenter. The POST method is also used to execute specific business processes, such as assigning an activity.

A POST consists of the POST method 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 may contain 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 using Cloud 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 marks an activity as complete 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.