Structure of an API call
General parameters for all requests:
| Parameter | Description | Examples |
|---|---|---|
| Authorization (header, not a param) | OAuth 2.0 Bearer access token — see Synergist API Authentication | Authorization: Bearer <access_token> |
| Version | Version of the API | version=6 |
| Page (optional) | Data page to return, page numbering starts at 0 | page=1 |
| Rows (optional) | Number of records/rows to return. 0 = return all rows | rows=10 |
Synergist API call
This example URL would get system information.
GET /jsonapi/system.json?action=version&version=6
Authorization: Bearer <access_token>Legacy username/password alternative:
GET /jsonapi/system.json?action=version&version=6&user=<username>&password=<password>Called using a browser
http://<SERVER>/jsonapi/system.json?action=version&version=6
Authorization: Bearer <access_token>Called using a browser (legacy username/password alternative)
http://<SERVER>/jsonapi/system.json?action=version&version=6&user=<username>&password=<password>Returns
"responsecode": 1,
"responsestatus": "OK",
"errorcode": 0,
"errormessage": "",
"responsemessage": "",
"warningmessage": "",
"success": true,
"data": [
{
"uuid": "E646889F48DD423CA1300491A31E8C50",
"systemparameters_versionno": 12.7,
"systemparameters_versionrevision": "d",
"variable_apiversion": "4"
}
][
{
"uuid": "E646889F48DD423CA1300491A31E8C50",
"systemparameters_versionno": 12.7,
"systemparameters_versionrevision": "d",
"variable_apiversion": "4"
}
]
}New integrations should authenticate via an OAuth 2.0 Bearer access token (see Synergist API Authentication) rather than passing credentials in the URL, as in the examples above. The legacy user=/password= and hashed sha512password= query-string mechanisms are still supported for existing integrations — see that document's HTTP Basic Auth section (and Hashing - Sha512 for how to obtain the hash) if you're still migrating off them.
e.g. (OAuth 2.0):
http://<SERVER>/jsonapi/diary.json
Authorization: Bearer <access_token>e.g. (legacy username/password):
http://<SERVER>/jsonapi/diary.json?user=<username>&password=<password>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 |
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>