Standard Request/Response Envelope

Our API always return any response in the standard response envelope.

The format of the envelope is -

Messages - This property is used to give some message to the consumer.

When API is unable to process the request you will receive error code and message inside the messages.

Data - Contains response data. it can be array for summary representation or it can be single item for detail representation.

HasMoreData -Indicates if there is more data that you can access by going to next page.

PagingData - Gives information about the paging details.

RowsPerPage - page size of the current response.

PageNumber - page number of the response.

TotalNumberOfPages - total number of pages available on server for the request. (Returns -1 if user has not set the count or countOnly query parameters in request).

TotalRowCount - total number of records available on server for the request.(Returns -1 if user has not set the count or countOnly query parameters in request).

Error Handling

This API uses standard HTTP status codes to indicate the status of a response.

Simple errors

Below is an example of a response for a bad request sent to create instance, where user tries to set the effective date with an incorrect date string ‘13/13/2001’ to the create request body a validation error must be triggered with following message / output response.

Sample Error Response

All error objects have code, message and field properties so that your client can understand what the problem is.

These are the possible validation error codes:

Request Headers

Response Headers

Summary Representation

When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the "summary" representation of the resource. (Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the "detailed" representation.)

Example:

GET /agreements

curl -k -i -H "Content-Type: application/json"\ 
-H "X-Token: {api-token}"\ 
-X GET 'https://{host-name}/agreements'

When you get a list of agreements, you get the summary representation of each agreement.

Sample Response

The documentation provides an example response for each API method. The example response illustrates all attributes that are returned by that method.

Detailed Representation

When you fetch an individual resource, the response typically includes all attributes for that resource. This is the "detailed" representation of the resource. (Note that authorization sometimes influences the amount of detail included in the representation.)

In detail representation you can also use expand query parameters to get the relationship in the same response. Please refer to expand section for more details.

Example: GET /agreement/bb1aadf3-8aee-494b-a6f5-5f8dd15357f0?expand=attributes

curl -k -i -H "Content-Type: application/json"\ 
-H "X-Token: {api-token}"\ 
-X GET 'https://{host-name}/agreements/{agreementID}?expand=attributes'

When you get an individual agreement, you get the detailed representation of the agreement. Sample Response

The documentation provides an example response for each API method. The example response illustrates all attributes that are returned by that method.

Partial Response

By default, the server sends back the default representation of a resource after processing requests. For better performance and saving bandwidth, you can ask the server to send only the fields you really need and get a partial response instead.

To request a partial response, use the select request parameter to specify the fields you want returned. You can use this parameter with any request that returns response data.

For example,

GET /agreements?select=id,name

curl -k -i -H "Content-Type: application/json"\ 
-H "X-Token: {api-token}"\ 
-X GET 'https://{host-name}/agreements?select=id,name'

Sample response