This page explains the Total Synergy APIs and our customers and partners should read this to understand how to integrate with our Synergy cloud product.
Total Synergy supports two environments.
Total Synergy supports two authentication types:
Synergy API is an integrated product. If you want to create an Application that integrates with Synergy you must first add an application through this page.
In order to create your first application you must register a Synergy account. Once you are logged in you can access your applications via the application home page
From this page you can create, edit and delete your applications.
When you create a new application you must provide your application name, organisation, callback URL and a variety of other fields.
Once you have created an application, the public key and private key will be automatically generated for your use.
Other organisations cannot access your application until the Synergy team approves it. This means users outside of your testing environment cannot access it, as it will not appear in the Synergy application library
To ensure your application is accepted by the Synergy team, you must provide a valid website URL, detailed description and an application image for use in the Synergy application library
To request approval:
Synergy API is based on authenticating requests via an OAuth token
You will first need to generate a user OAuth token. Follow these steps:
Gain a token request code via a user login. Once you have logged in, you will receive a token request code in the redirect URI you provided. You will see the code under the response parameter 'code'. To make the user login request use the following structure:
https://app.totalsynergy.com/OAuth2/Authorize?ApplicationKey=YOURAPPLICATIONKEY&RedirectUri=/AuthenticationResponse&tenant=For Desktop applications you can set the Redirect URI to https://desktop and monitor the browser for a change to the URL https://desktop/?code=XXXX.
You will then need to retrieve the token for the next step. You can also include the query parameter &simple=true if you require a login without javascript on the page.
Using your request code, perform a POST to /Oauth2/GetAccessToken to recieve the user access token. Do this from your server application, as it requires your secret key. The POST request must contain your application public key,
application secret key, token request code and the grant_type.
The following code shows how to perform this operation using an angular HTTP request.
$http({
url: 'https://api.totalsynergy.com/api/v2/Oauth2/GetAccessToken,
method: 'POST',
data : {
applicationKey : "YOURAPPLICATIONKEY",
ApplicationSecret : "YOURAPPLICATIONSECRET",
code : "asdjhsnd3d.sad839jdm",
grant_type : "authorization_code"
}
});
The server will respond with your OAuth token and the given expiry date for the token. To use the access token in any subsequent API calls you add the header 'access-token' and assign it the value of the newly generated user OAuth token.
The token contains a refreshToken that lasts for 1 month. To refresh the access token, POST the following request:
$http({
url: 'https://api.totalsynergy.com/api/v2/Oauth2/RefreshAccessToken,
method: 'POST',
data : {
applicationKey : "YOURAPPLICATIONKEY",
ApplicationSecret : "YOURAPPLICATIONSECRET",
refreshToken: "YOURREFRESHTOKEN"
grant_type : "authorization_code"
}
});
To make an API call you must first generate a user OAuth token using the above steps. As the API does not allow CORS, web SPAs should use a server proxy to call the API.
All Synergy API requests share the same format. Use https://api.totalsynergy.com/api/v2/ as the base URL and append the
action you wish to perform. API requests must also contain the user OAuth token under the header access-token. The following examples
demonstrate a typical API request :
@POST("api/v2/Timers")
Call<Item> createTimer(@Header("access-token") String accessToken, @Body Timer timer);
$http({
url: 'https://api.totalsynergy.com/api/v2/Organisation/MySlug/Timesheet/Leaderboard',
method: 'POST',
headers: {'Content-Type': 'application/json','access-token' : key}
});
All responses are encapsulated as JSON. Strongly typed data types such as dates are serialized and delivered in string format. Synergy API responses all embed standard REST based characteristics:
Successful responses return with a HTTP 200 status code
Unsuccessful responses return with a status code reflecting the error. Synergy API response codes include not found 404,
unauthorized action 401 and internal server error500
Synergy reserves POST and PUT for certain CRUD operations. A PUT method will create new data in Synergy,
whereas a POST will either create new data or update existing data. Likewise, GET is used for requesting data and
DELETE for the removal of data in Synergy.
Note that the free API has limitations:
We recommend exercising extreme care and caution with any development, to protect confidential data including personal data and confidential business data.
With access to the API, the developer has greater accessibility to potential confidential and personal information which the API developer is responsible for keeping safe.
The API developer must also keep any API keys/tokens/OAuth safe and secure from unauthorised parties using them. This could include keeping API keys/tokens/OAuth out of webconfig or other such files, instead keeping them in some sort of encrypted storage to be decrypted on the fly when required.
A sample OAuth application is available for download at Total Synergy sample application.
A live version of the sample web app is here Live sample web application.
For batch processing or internal applications built by customers or while doing development, use a static key to call APIs.
Retrieve the The static key by following the steps below. Follow the same procedure as the access-token detailed above. To acquire a static token:
The Total Synergy API can be called by Power BI using the rest connector.