API Documentation

Getting Started With Timeero Public API

🏃 Get Started

With the Timeero API, you can seamlessly talk with our servers in seconds. The Timeero API is based on REST principles. It’s effortless to write and test applications. All access to the API occurs over an SSL-encrypted secure channel. Every Timeero administrator can generate a unique access token to access the Timeero public APIs

🌐 Endpoint

All URLs referenced in the documentation have the following base:

🌐

https://api.timeero.app/api/public/

🚧

Authentication 🔐.

Authentication is required to properly access Timeero API. Once you are authenticated, you can use an access token for subsequent requests. All requests via API access are made with administrative privileges hence tokens must be treated very securely.

🔑 How to obtain the access token key

📘

How to obtain the access token key 🔑

We allow access tokens to be created through our web application by going to the Integrations > Public API > Configurations page. The tokens have no expiration but can be expired when explicitly revoked using the revoke key button in the configuration page, once the access key has been generated.

You will click on the **Generate API key**

You will click on the Generate API key

Click on **❏** to copy.

Click on ❏ to copy.

🛎️ Requests

The Timeero Public APIs are accessed from the https://api.timeero.com domain. All the request body is sent and received in the JSON format and all API requests require authentication.

🌐

https://api.timeero.com/api/{api-version}/{resource}/{resource-id}

Where:

  • https:// - the API is served ONLY over secure HTTP
  • api.timeero.app - the API's endpoint domain.
  • api - the identifier for stateless Rest APIs
  • api-version - the API version identifier e.g. v2. (optional - provide only if versioning is done)
  • resource - the service slug's API endpoint e.g. users.
  • resource-id - the service slug's ID e.g. 123.

All requests to the API must be made over SSL (https:// not http://).

😎 HTTP Verbs

VerbDescription
HEADQuery HTTP headers
GETRetrieve resources
POSTCreates resources or executes custom actions
PUTPartial update of resources
DELETEDelete resources

Query Parameters

Filtering

The items in Timeero can be filtered by applying optional sorting, searching and pagination query parameters.

Go through an endpoint's parameters description to check which properties are filterable for that endpoint.

Example: To retrieve active users with an admin role, use

curl -H 'Authorization: <Access-Token>' 
		 --request GET 'https://api.timeero.app/api/public/users?active=1&role=1'

Pagination

You can control the maximum number of collections that are returned using the page_size query parameter. To choose a page, use the standard page query parameter.

The default page is always the first one i.e 1 and the default limit for the number of collections is 10. Page numbering is 1-based and omitting the ?page parameter will return the first page.

curl -H 'Authorization: <Access-Token>' 
		 --request GET 'https://api.timeero.app/api/public/users?page=2&page_size=3'

Sorting

You can control in what order, according to the provided criteria, how to sort resource collections using the query parameter sort.

The ?sort query parameter takes one or more field names separated by , to sort the collections.

The default sort order is ascending. If you want to change the sort order to descending, prepend a - to the sort field passed.

To check what properties are sortable, go through an endpoint's parameters description.

For example, to get a list of users and sort it by firstName in ascending order, use:

curl -H 'Authorization: <Access-Token>' 
		 --request GET 'https://api.timeero.app/api/public/users?sort=firstName'

To get a list of users and sort it by firstName in descending order, use:

curl -H 'Authorization: <Access-Token>' 
		 --request GET 'https://api.timeero.app/api/public/users?sort=-firstName'

If you want to sort by multiple fields, you can give the sort values for those fields separated by ,

To get a list of users and sort it by both firstName and roleId in ascending order, use:

curl -H 'Authorization: <Access-Token>' 
		 --request GET 'https://api.timeero.app/api/public/users?sort=firstName,roleId'

Searching

You can search the collections using the query parameter search.

The ?search query parameter takes a value to search the collections with the matching value provided.

To check what properties are searchable, go through an endpoint's parameters description.

For example, to search a user with the name john, use:

curl -H 'Authorization: <Access-Token>' 
		 --request GET 'https://api.timeero.app/api/public/users?search=john'

Filter By Date Range

You can filter the collections using the query parameter date_range to get the collections between the provided date range.

The ?date_range query parameter takes the date values separated by ,. The format for the date is expected to be Y-m-d

For example, to get a filter the collections between date 2022-01-01 and 2022-02-28 , use:

curl -H 'Authorization: <Access-Token>' 
		 --request GET 'https://api.timeero.app/api/public/timesheets?date_range=2022-01-01,2022-02-28'