Overview

This document defines the Synergist XML/JSON API which is based on REST.

A request needs to include the parameters required for the action being taken. The Synergist username and password or session are always mandatory parameters. The API version number is a mandatory parameter.

For example:

GET /jsonapi/users.json?user=user&password=user&action=newsession&version=3

The above URL would create a new session for the user.

GET /jsonapi/system.json?user=user&password=user&action=version&version=3

The above URL would get system information.

General parameters for all requests:

parameter	description
user	Synergist login ID
password	Synergist password
page (optional)	Data page to return, page numbering starts at 0
rows (optional)	Number of records/rows to return. 0 = return all rows
version	Version of the API – currently 3
username	Alternative Synergist username to use for data retrieval on behalf of a different user

XML Response

When a response is sent which contains multiple records, the root element of the XML tree will have the following attributes:

attribute	description
TotalRows	this will be the total number of records/rows in the selection, regardless of page requested
TotalPages	this will be the total number of pages available, based on the rows parameter supplied
MorePages	this will be True if further pages of data are available or False if you have fetched the last page

In case of any error, the Synergist server will return an HTTP 404 error together with an XML structure containing the error details:

<Responses>
    <Error ErrorID="404500">
        <ErrorText>invalid action companylist</ErrorText>
    </Error>
</Responses>

The following errors are possible for all requests:

ErrorID	ErrorText
404001	no credentials supplied
404002	invalid credentials supplied
404003	account disabled
404004	request not recognised

JSON Response

When a response is sent which contains multiple records, the root of the JSON string will have the following attributes:

attribute	description
totalrows	this will be the total number of records/rows in the selection, regardless of page requested
totalpages	this will be the total number of pages available, based on the rows parameter supplied
pagenumber	the current page returned in the set
pagerows	number of rows requested

A successful response will contain the following attributes at root level:

attribute	description
Success	true
Responsemessage	a context response message
Responsecode	response code indicator
Errormessage	empty string
Errorcode	0
Data	the root json element containing the data result rows

A response error will contain the following attributes at root level:-

attribute	description
Success	false
Errormessage	any error context message
Errorcode	response code indicator