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 register and use an actiTIME trial installation.
Please note:
- API is supported starting from actiTIME 2019.2 version;
- API is available in the paid versions of actiTIME Online and actiTIME Self-Hosted.
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:
- modify users’ time-track
- 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:
- Customers
- Projects
- Tasks
- Time-Track
- Leave Time
- Users
- Departments
- Time Zone Groups
- Types of Work
- Workflow Statuses
- Leave Types
- Cost of Work Rates
- Info
- Batch
You can also use REST Hooks subscriptions for your integrations.
Please note:
- different permissions may be required to access the data using different requests;
- if some actiTIME feature is turned off, corresponding data are returned in requests responses nevertheless.
Authorization
actiTIME requires applications to authorize all requests using basic authentication scheme: user’s login and password should be specified. 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 <YOUR_ENCODED_LOGIN_CREDENTIALS>"
or
curl -X GET "<actiTIME URL>/api/v1/customers/6" -u "username:password"
If the authorization has failed, 401 status code is returned.
The authorization may fail due to the following reasons:
- user has provided invalid credentials or no credentials at all.
- user has provided valid credentials 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
- PUT
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. Usually response message includes response headers and response body. If requested field is empty, ‘null’ value or empty string will be returned. The response message can also be empty for some operations.
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 the properties of a customer with ID=6:
curl -X GET "<actiTIME URL>/api/v1/customers/6" -H "accept: application/json; charset=UTF-8" -u "username:password"
Retrieve a 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" -u "username:password"
Update resource with the PATCH method
You can update the 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 "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "{ \"name\": \"Customer #15\"}"
Create a 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 "Content-Type: application/json; charset=UTF-8" -u "username:password" -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" -u "username:password"
Renew resource data with the PUT method
You can delete or set new data for an object by submitting the PUT request.
Use the following request to change a user’s regular cost of work rate and overtime rate in the system to 15 and 20 respectively (since leave rates are omitted from the request, their values will be set up in actiTIME using the default coefficients):
curl -X PUT "<actiTIME URL>/api/v1/userRates/16" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "[ { \"dateFrom\": \"2023-04-01\", \"regularRate\": 15, \"overtimeRate\": 20 }]"
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 the 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 the 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).