Edition: Professional, Business, Enterprise
User-level: All users
The API (Application Programming Interface) for Total Synergy allows you to interact with the platform programmatically, enabling you to create, retrieve, update, and delete data within the system.
Developer documentation
You can access the API documentation directly from this link here: https://developers.totalsynergy.com/. This documentation is comprehensive, covering information you need to know about what environments are used, authentication options, application development, and existing integrations.
The list of endpoints available is also in this documentation. You can access that list from the main documentation page, or directly from this link here: https://developers.totalsynergy.com/swagger/ui/index.
How to find your API key
Your API key will be used in multiple applications for Synergy, but most commonly will be used in static authentication. To find your API key in Total Synergy, follow these steps:
Log in to your Total Synergy account.
Click on your profile icon in the top right corner of the screen, and select "Edit Profile" from the dropdown menu.
Click on the ellipses (three dots) and select "API Key" from the options
Your personal API key will be displayed in this section. There will be two keys available, with different expiry times (one, and three years). Choose the appropriate expiry when building API queries in the program you're using.
Your API key contains information about your user such as your username, email, expiry, and security access level, so it's best not to share it externally.
Because it contains your access level, the API will know what information you have access to. This can mean that some endpoints will provide you less information, or be completely off-limits to you, depending on your access level. For things like Power BI dashboard integrations, we suggest using the API key of a System Administrator, to ensure full access is available.
Limitations
All subscription levels include a base level of API usage, with access to all endpoints. The limitation is the number of calls you can make per day: 300 calls per day, with a maximum of 50 calls for the transaction endpoint (used for creating timesheets).
If you need more calls, you can purchase the Premium API add-on from the subscription page for increased limits. Premium API allows up to 60,000 calls per day, and up to 20,000 calls from the transaction endpoint. For more information about enabling add-ons, see this article here: https://help.totalsynergy.com/en/articles/6569166-enabling-add-ons
Finding IDs
When returning results, the items in your response unique ID's (e.g. Projects, Staff, Contacts). This will be the ID used for those items in the database. A project will have a database ID that is not the same as the project number that you see in the web interface. Most endpoints will allow you to search for a specific ID by including a parameter, usually 'criteria.Id'. Check the specific endpoint documentation for the exact parameter to use.
To get these ID's, you have a couple of options. You can either run a query for the endpoint without the parameter to get a list of all the items and their ID's, or in some cases you can get them from the URL in Synergy.
For example, when you're on a project page, the ID of the project will be in the URL:
Other things like Contacts and Staff will show their ID's in the URL as well. When you're needing to get the ID for something from Synergy for use in the API, looking at the URL is a good place to start.
Where to next?