• Create an application
  • Public application
  • Oauth
  • How to make a call
  • Json responses
  • CRUD
  • Request limiting

Getting started

How to set up?

Create an application

Synergy API is an integrated product. This means you must first create an application to gain access to the API.

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

Here you can create, edit and delete your applications. While creating 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.

Application Approval

Public application

When you first create an application it will not be accessible to other organisations until it has been approved by the Synergy team. This means it will not be found in the Synergy application library and cannot be accessed by Synergy users outside your testing enviornment.

To request approval, go to the application home page and view the details of the application you wish to make public. Clicking on the 'Request Approval' button will notify the Synergy team that your application is ready for approval. If the application satisfies all requirements you will recieve an email notifying you that your application has been approved. Once the application has been approved you can go back to the details page of the application and toggle the 'Is Public' field.

In order to be accepted by the Synergy team ensure that you have provided a valid website url, detailed description and an application image that can be used in the Synergy application library.

How to access?

Oauth

Synergy API is based on authenticating requests via an oAuth token

To generate a user oAuth token you must follow these steps:

  1. Gain a token request code via a user login. Once the user has logged in, the token request code will be sent to the redirect URI you provided. The code will be available 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 RedirectUri to https://desktop and monitor the browser for a change to the url https://desktop/?code=XXXX, then retreive the token to be used in the next step. You can also include the query parameter &simple=true if you require a login without javascript on the page.

  2. Now that you have your request code, perform a POST to /Oauth2/GetAccessToken to recieve the user access token. 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/Oauth2/GetAccessToken, 
    		method: 'POST',
    		data : {
    			applicationKey : "YOURAPPLICATIONKEY",
    			ApplicationSecret : "YOURAPPLICATIONSECRET",
    			code : "asdjhsnd3d.sad839jdm",
    			grant_type : "authorization_code"
    		}
    	});
    									
  3. The server will respond with your oAuth token and the given expiry date for the token. To use the access token in subsequent API calls you add the header 'access-token' and assign it the value of the newly generated user oAuth token.

  4. 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/Oauth2/RefreshAccessToken, 
    		method: 'POST',
    		data : {
    			applicationKey : "YOURAPPLICATIONKEY",
    			ApplicationSecret : "YOURAPPLICATIONSECRET",
                            refreshToken: "YOURREFRESHTOKEN"
    			grant_type : "authorization_code"
    		}
    	});
    									

How to make a call?

Api call

To make an api call you must first generate a user oauth token using the above steps.

All Synergy Api requests share the same format. You 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 :

Java - Retrofit 2
@POST("api/v2/Timers")
Call<Item> createTimer(@Header("access-token") String accessToken, @Body Timer timer);
								
Javascript - Angular

$http({ 
  url: 'https://api.totalsynergy.com/api/v2/Organisation/MySlug/Timesheet/Leaderboard',
  method: 'POST',
  headers: {'Content-Type': 'application/json','access-token' : key}
});
									

JSON responses

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:

  1. Successful responses return with a HTTP 200 status code

  2. 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

CRUD

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.

Request Limiting

Api requests are currently limited to 5000 requests an hour. Once exceeded, users will recieve a 429 error status code "Rate Limit exceeded". On every hour, UTC time, the request count will return to 0.