Getting Started

Welcome to the Empiraa API - your gateway to easily importing or sharing data with other systems.

Quick Start

  1. You'll need your Empiraa account to sign-in to the API platform. If you haven't already registered for Empiraa, you can do so here.

    • Empiraa Pro or greater is required to access the API (Applies to both Trial & Paid)

  2. (Optional - requires an additional user license)

    It is recommended that you setup an account within Empiraa specifically for integration. The account used to register in the Empiraa API Management portal is also used to determine the security and data access the API will have to Empiraa. Setting up a separate account will allow you to:

    • Change the permissions of the integration account without impacting your own permissions within Empiraa.

    • Stop the integrations by disabling the integration account and you won’t personally be impacted.

    • Record changes (e.g. Updates to Objective Actuals) against the integration account for auditing purposes.

    • Prevent API integration from being disabled should the user that signed up to the API ever be removed from Empiraa (e.g. left the company)

  3. Click the "Sign in" link at the top right hand corner of this site; the Empiraa API Management portal. If you setup an integration user account (described in the 'optional' step above), sign-in with the intergration user account.

  4. Once logged in, the API Keys and Tenant ID shown in your profile page are required to use the Empiraa API

    • You can use the API from any tool or product that supports REST API's, including Zapier, Power Automate and more.

  5. Click on the 'APIs' menu item to check out the API functions (GET for retrieving data and POST for updating data)

  6. If you don't have a tool or haven't written any code just yet then don't worry! You can test the API's by selecting the "try" button from the API portal. See API calls and authorisation for more information.

    • You'll need to copy/paste your TenantID & API-Key into the appropriate fields for the test to be successful

    • The API "test" button will return results of the API call in the pop-up window

  7. Read all of the information below to get a full understanding of how to use the API

API calls and Authorization

Apply the following inputs to the API header:

API-Key Empiraa API subscription key. This is unique for each organisation and user.
Tenantid Unique Identifier for the Empiraa organisation. This will be the same for all users in a single organisation.

These values are found under the 'Profile' menu once logged into the Empiraa API management portal.
Make note of the Tenant ID and API Keys, keep them safe and don't share them with others.

The API will use the permissions you've been assigned in Empiraa, therefore, results returned via the API will be limited to what you can already see within Empiraa.

Paging

Each Empiraa API uses a page mechanism whereby each API call will progressively return 200 rows of data for each API call.
In order to retrieve the entire result set, you are required to call the API repeatedly passing an incrementing $Offet parameter until you receive an empty result set.

Sandbox

An optional sandbox can be created for your user account. This can be done within the 'Profile' menu once logged into the Empiraa API management portal.

The sandbox is an area for you to go crazy and test the Empiraa API without impacting your work. The results of your API calls to the sandbox will be shown inside of your own Empiraa sandbox organisation (pretty cool eh?). The sandbox organisation is affectionalty known as 'Go Nutz for Donutz'.

To access the sandbox UI, login to Empiraa (app.empiraa.net) and go to your user profile, then click on "Switch Organisation". The sandbox will appear in the list of Organisations you have acess to.

You'll need to use the sandbox 'TenantID' (also found in the Profile page in the Empiraa API management portal) to ensure data is written to the sandbox and not your production environment.

There is a limit of a single sandbox per user, regardless of how many organisations you may have.

Once you are happy with your testing, make sure to change the 'TenantID' to use the production API's.


Rate limits

The system is configured to apply rate limits to the number of calls you can make per Organisation.
Attempting to exceed these limits will result in a reduced performance or increased API wait times.

  • Minute Limit: 50 calls per minute (Empiraa Pro) and 100 calls per minute (Empiraa Enterprise)

  • Daily Limit: Unlimited calls per day for standard users and unlimited for premium users

  • Sandbox: Limited to 50 calls per minute

Rate limits are applied per Tenancy (i.e. The total of all API calls per tenancy, regardless of the number of API users)

Quotas

There are currently no quoatas enforced.

Objective Date Alignment

An important aspect to note is how actual data is stored and used within an Objective in Empiraa.

Empiraa uses the 'end' date of a given period to determine alignment of Week's, Month's and Year's.
So if you setup a monthly objective for January and tell (via the API) that the objective value as at 15th Jan is '100', then Empiraa will set the 31st Jan to '100'.

This is important to remember when passing $Date to update an Objective in Empiraa - it will always be set to the nearest 'end' date for a given objective period. Results need to be summed to the total of the objective period prior to loading into Empiraa via the API.

Here are some examples of how the end date is calculated:

Weekly objective
If the week is between 1st and 7th of Jan, the objective value will be set as at 7th Jan (last day of the week).
If the week starts on 30th of Jan and finishes on the 5th of Feb, the objective value will be set as at 5th Feb (last day of the week).

Monthly objective
If Jan is the month of the objective, all data will be stored as at 31st Jan

Quarterly objective
All data will be stored as at the last day of the quarter.
If using calendar quarters, this would be Mar 31st, Jun 30th, Sep 30th and Dec 31st.