Overview

The actiTIME API is a REST API with a JSON payload that ensures direct interaction with actiTIME. It allows you to get users’ time-track and leave time, create customers, projects and tasks, and much more.

Detailed API documentation is available at the following URI:

<your actiTIME URL>/api/v1/swagger

There you can also execute requests, but it’s highly recommended NOT TO USE YOUR PRODUCTION DATA FOR TESTING PURPOSES.

Instead, you can use demo data of the demo installation and test API at the following URI:

https://demo.actitime.com/api/v1/swagger

To test API, you should be authorized. You can authorize as administrator (username: “admin”, password: “manager”) or any other system user (username and password are the same by default).
Note that demo data is reloaded every 3 hours.

You can also register and use an actiTIME trial installation for API testing purposes.

Please note that API is supported starting from actiTIME 2019.2 version.

API Features

actiTIME API allows to collect data for various purposes, for example:

  • preparing data backups;
  • performing business analysis;
  • synchronizing data between actiTIME and external systems;
  • exporting data from actiTIME to external systems;
  • creating your own custom reports, etc.

It also enables data import from external systems to actiTIME to reduce time spent on routine work operations.

With actiTIME API, you can extract the following data from actiTIME:

  • users’ time-track;
  • users’ leave time;
  • lists of customers / projects / tasks;
  • properties of specific customers / projects / tasks;
  • lists of customers / projects / tasks comments;
  • user list & users’ properties;
  • departments list & departments’ properties;
  • time zone groups list & time zone groups’ properties;
  • leave types list & leave types’ properties;
  • types of work list & types of work properties;
  • workflow statuses list & workflow statuses properties;
  • system settings.

With actiTIME API you can also:

  • create new customers / projects / tasks;
  • update customers’ / projects’ / tasks’ properties;
  • delete customers / projects / tasks;
  • create new workflow statuses;
  • update workflow statuses’ properties;
  • delete workflow statuses.

Resources

actiTIME API is organized by resources representing different actiTIME objects, such as time-track, tasks, users. etc.

The following resources are supported:

Please note:

  • the resources and resource methods require different permissions to access corresponding data;
  • if some actiTIME feature is turned off, corresponding data are returned in requests responses nevertheless.

Authentication

actiTIME requires applications to authenticate all requests with basic authentication schema using user’s login and password. Security of entered credentials is provided by the https protocol.

Each request should include authorization data in header. For example:

curl -X GET "<actiTIME URL>/api/v1/customers/6" 
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

or

curl -u "username:password" -X GET "<actiTIME URL>/api/v1/customers/6"

If the authentication has failed, 401 status code is returned.

The authentication may fail due to the following reasons:

  • user has provided the wrong credentials or no credentials at all.
  • user exists but cannot be authorized (user account is disabled or not activated, user’s hire date is set to the future).

Working with API

The following HTTP methods are supported:

  • GET
  • PATCH
  • POST
  • DELETE

For the GET and DELETE methods, no request body is required. Parameters should be included in the URL query string.

The POST and PATCH methods require a request body specified in JSON format that contains additional information, such as values for the resource’s properties.

A request for reading from a resource or writing to it should be as follows:

<actiTIME URL>/{version}/{resource}?query-parameters

The components of a request include:

  • HTTP method – The HTTP method used on the request to actiTIME.
  • {version} – The version of the actiTIME API your application is using. Currently only ‘v1’ version is supported.
  • {resource} – The resource in actiTIME that you’re referencing.
  • query-parameters – An optional set of parameters to modify the request or response.

After you make a request, a response is returned that includes:

  • Status code – An HTTP status code that indicates success or failure.
  • Response message – The data that you requested or the result of the operation. The response message can be empty for some operations. Usually it includes response headers and response body.

actiTIME API allows to perform various actions using GET, PATCH, POST and DELETE methods.

Retrieve resource with the GET method

You can get all available properties of an object by sending a GET request to the resource’s endpoint URL, providing the ID of the necessary object.

Use the following request to get properties of a customer with ID=1:

curl -X GET "<actiTIME URL>/api/v1/customers/1"
-H "accept: application/json; charset=UTF-8"
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Retrieve list of resources with the GET method

You can get a list of objects by sending GET request to the resource’s endpoint URL. Use a query string following the endpoint URL to specify filters and sorting orders for your request. Additional data can also be included in the response.

Use the following request to get a list of tasks that have the word ‘testing’ in their names limited to 10 tasks, skipping first 20 tasks, alongside with their customers and types of work:

curl -X GET "<actiTIME URL>/api/v1/tasks?offset=20&limit=10&sort=%2Bname&words=testing&includeReferenced=customers%2CtypesOfWork"
-H "accept: application/json; charset=UTF-8"
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Update resource with the PATCH method

You can update properties of an object by sending a PATCH request to the resource’s endpoint URL, providing the object’s ID. Include in your request only the properties that need to be updated. Also make sure you’ve set the “Content-Type: application/json” header in your request.

Use the following request to change the name of the customer with ID=2 to ‘Customer #15’:

curl -X PATCH "<actiTIME URL>/api/v1/customers/7"
-H "accept: application/json; charset=UTF-8"
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="
-H "Content-Type: application/json; charset=UTF-8"
-d "{ \"name\": \"Customer #15\"}"

Create resource with the POST method

You can create an object by sending a POST request to the resource’s endpoint URL. Mandatory fields must be specified in the request. Also make sure you’ve set the “Content-Type: application/json” header in your request.

Use the following request to create a new workflow status from ‘Completed’ group with a name ‘Won’t Fix’:

curl -X POST "<actiTIME URL>/api/v1/workflowStatuses"
-H "accept: application/json; charset=UTF-8"
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="
-H "Content-Type: application/json; charset=UTF-8"
-d "{ \"name\": \"Won't Fix\",\"type\": \"completed\"}"

Delete resource with the DELETE method

You can delete an object by sending a DELETE request to the resource’s endpoint URL, providing the ID of the object.

Use the following request to delete the project with ID=10 and revoke the approval status of approved weeks:

curl -X DELETE "<actiTIME URL>/api/v1/projects/10?revokeApprovedWeeks=true"
-H "accept: application/json; charset=UTF-8"
-H "authorization: Basic YWRtaW46bWFuYWdlcg=="

Errors Processing

actiTIME formats response bodies in JSON and uses HTTP status codes to indicate the success or failure of an API request.

If the request has succeeded, 200 (OK) or 204 (No Content) HTTP status code will be returned.

If the request has failed, other status codes will be returned. Different errors can have the same status code. The exact cause of the failure is defined by the ‘key’ and the ‘message’ parameters included in the response body. The ‘key’ parameter value identifies the error. The value of the ‘message’ parameter is a human readable message intended to help solve the problem.

403 Status Code Example

{
  "key": "api.error.customer_exists",
  "message": "Customer with specified name already exists"
}

In the table below, HTTP status codes are listed that you may encounter when using actiTIME API, and brief descriptions of the errors they indicate.

Code Explanation
200 Request has succeeded.
204 Request has succeeded. Object is successfully deleted.
400 Invalid authentication scheme is used. Only Basic Authentication scheme is supported.
400 Object with specified name already exists.
400 Cannot parse provided arguments.
401 User is not authorized (invalid credentials).
401 User exists but cannot be authorized (credentials are valid).
403 User does not have access to the specified object or lacks permissions to perform the requested operation.
404 Object with given ID does not exist.
500 Internal SQL Error.
429 Too many requests.

Some methods may have another error codes not listed above.

Rate Limiting

actiTIME has an API throttle. It blocks user accounts that submit more than 100 requests per 1 second or 1000 requests per minute. We reserve the right to modify these restrictions in the future, but they are always sufficient for your application to properly interact with actiTIME.

When the number of submitted requests exceeds the request rate limits, the throttle is triggered. The requests beyond the limit cannot be executed successfully, and error code 429 (Too Many Requests) is returned. Time in seconds remaining until the requests can be executed again is shown in the Retry-After HTTP header.

Please take these limitations into account when developing your applications. We recommend that you use caching where possible.

For authorized users

If the rate limit is not exceeded, the following headers are returned:

Header Description
X-Ratelimit-Remaining: n Shows how many requests are left in the current time window.
X-Ratelimit-Reset: n Shows seconds remaining until the end of the current time window and reset of the rate limit.

If the rate limit is exceeded, the 429 (Too Many Requests) error code and the following headers are returned:

Header Description
X-Ratelimit-Remaining: n Shows how many requests are left in the current time window.
X-Ratelimit-Reset: n Shows when the current time window ends (in seconds from the current time) and when the rate limit resets.
Retry-After: n Same as X-Ratelimit-Reset: shows time (in seconds) remaining until new requests can be sent.

For unauthorized users

After 3 failed attempts to send a request with invalid credentials (login-password) per 10 seconds, the IP is banned for 1 minute (403 (Forbidden) error code is returned).