API FAQ

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.

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.

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:

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.

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

Each endpoint will have a parameter that can be used to control the size of the response. For any endpoint that does not use keyset pagination, you will be able to use the criteria.pagesize parameter to set a page size up to 1000 records.

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.

Total Synergy has multiple environments, most of which are used internally by our development and QA teams for testing. The production environment is the one you'll use for day-to-day access to your organisation's data.

The first part of the URL will be the environment. e.g. app.totalsynergy.com is the live production environment.

The production environment also has two API environments available for you to use. So when building your API queries, you will use one of three environments:

Customers also have access to a UAT (User Acceptance Testing) environment. This environment is a weekly-refreshed copy of your production database and is useful for testing with your own data without affecting your live records:

A beta (preproduction) environment is available upon request. This environment does not contain your organisation's data and is ideal for testing new or upcoming functionality. If you would like temporary access, please contact Support. The environments for API access in beta are: