Customers Resource

The following requests are supported for operations with customers via actiTIME API:

GET/customers/{id}
GET/customers
GET/customers/{id}/comments
PATCH/customers/{id}
POST/customers
DELETE/customers/{id}

Customer Properties

Customer properties available via API:

Property Description
id Unique customer identifier.
name Customer name.
archived Customer status. Possible values: true (archived), false (active).
created Customer creation date and time.
description Customer description.
url Customer URL.

Alongside with the properties listed above, the ‘allowedActions’ property is also returned. The ‘allowedActions’ property shows whether the user can modify or delete this customer. See the PATCH/customers/{id} and DELETE/customers/{id} requests to read more about the required permissions for these actions.

Required Permissions

Customer’s properties and comments can be retrieved by any user who can access the entire customer or at least one of its projects or tasks in:

Work Assignments, which allows to enter time-track for tasks and requires the “Enter Time-Track” permission,

or

Scope of Work, which allows to manage the entity and is granted under the following permissions:

  • Manage Accounts & Permissions (all customers belong to scope of work);
  • Modify & Approve Other Users’ Time-Track;
  • Manage Scope of Work;
  • Manage Cost & Billing Data.

Read more on available actions under various permissions in the User Guide.

Retrieve Customer Properties

Use the following request to retrieve all properties of the customer with given ID:

GET/customers/{id}

Also see the ‘Required Permissions’ section.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/customers/6" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "id": 6,
  "name": "Big Bang Company",
  "archived": false,
  "created": 1566950400000,
  "url": "<your actiTIME URL>/tasks/tasklist.do?customerId=6",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "description": "Building and testing a new generation spaceship"
}

More info on using this request is in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Retrieve List of Customers

Use the following request to retrieve a list of available customers with all their properties:

GET/customers

Also see the ‘Required Permissions’ section.

The request can be specified with several parameters:

Parameter Description
offset Pagination offset.
If provided, the first n customers will be not shown in the list.
limit Pagination limit.
If provided, the number of returned customers will be limited to n.
If not provided, the default value (1000) is used.
ids If provided, only customers with given IDs will be returned.
sort Sets sorting of the results.
Customers can be sorted by creation date or by name.
name If provided, only customer with exact name match will be returned.
words If provided, only customers containing all given words in their names will be returned.
archived If provided, only active or only archived customers will be returned.
If not provided, both active and archived customers will be returned.

Also see the ‘Required Permissions’ section.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/customers?limit=1000&sort=%2Bcreated&words=company" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "offset": 0,
  "limit": 1000,
  "items": [
    {
      "id": 6,
      "name": "Big Bang Company",
      "archived": false,
      "created": 1566950400000,
      "url": "<your actiTIME URL>/tasks/tasklist.do?customerId=6",
      "allowedActions": {
        "canModify": true,
        "canDelete": true
      },
      "description": "Building and testing a new generation spaceship"
    },
    {
      "id": 9,
      "name": "Our company",
      "archived": false,
      "created": 1566950400000,
      "url": "<your actiTIME URL>/tasks/tasklist.do?customerId=9",
      "allowedActions": {
        "canModify": true,
        "canDelete": true
      },
      "description": null
    }
  ]
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Retrieve List of Comments

Use the following request to retrieve a list of comments on the customer with given ID:

GET/customers/{id}/comments

The request can be specified with several parameters:

Parameter Description
offset Pagination offset.
If provided, the first n comments will be not shown in the list.
limit Pagination limit.
If provided, the number of returned comments will be limited to n.
If not provided, the default value (1000) is used.
includeReferenced Additional data that can also be included in the response:
– users that left the comments.

Example Request:

curl -X GET "&ltactiTIME URL&gt/api/v1/customers/7/comments?offset=0&limit=1000&includeReferenced=users" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "offset": 0,
  "limit": 1000,
  "items": [
    {
      "id": 8,
      "userId": 16,
      "created": 1553251940000,
      "updated": null,
      "updatingUserId": null,
      "text": "done"
    },
    {
      "id": 7,
      "userId": 1,
      "created": 1553207430000,
      "updated": 1553251833000,
      "updatingUserId": 1,
      "text": "please update customer description"
    }
  ],
  "users": {
    "1": {
      "id": 1,
      "active": true,
      "firstName": "John",
      "middleName": "",
      "lastName": "Doe",
      "departmentId": 5,
      "timeZoneGroupId": -1,
      "fullName": "John Doe"
    },
    "16": {
      "id": 16,
      "active": true,
      "firstName": "Daniel",
      "middleName": "",
      "lastName": "Alvarez",
      "departmentId": 7,
      "timeZoneGroupId": 3,
      "fullName": "Daniel Alvarez"
    }
  }
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Update Customer Properties

Use the following request to update properties of the customer with given ID:

PATCH/customers/{id}

Only the following properties can be updated: ‘name’, ‘archived’, and ‘description’.

Required Permissions

To be able to modify a customer, the user should have:

  • ‘Manage Scope of Work’ permission;
  • access to the customer in Scope of Work.

Example Request:

curl -X PATCH "&ltactiTIME URL&gt/api/v1/customers/49" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "{ \"name\": \"Old Projects\", \"archived\": true, \"description\": \"not to be used anymore\"}"

Example Response:

{
  "id": 49,
  "name": "Old Projects",
  "archived": true,
  "created": 1625501074000,
  "url": "<your actiTIME URL>/tasks/tasklist.do?customerId=49",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "description": "not to be used anymore"
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Create Customer

Use the following request to create a new customer:

POST/customers

While creating a customer, the following properties can be specified: ‘name’, ‘archived’, and ‘description’.
‘name’ field is mandatory, other fields are optional.

Required Permissions

To be able to create new customers in the system, the user should have:

  • the ‘Manage Scope of Work’ permission;
  • access to the entire Scope of Work.

Example Request:

curl -X POST "&ltactiTIME URL&gt/api/v1/customers" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json; charset=UTF-8" -u "username:password" -d "{ \"name\": \"New Projects\", \"archived\": false}"

Example Response:

{
  "id": 50,
  "name": "New Projects",
  "archived": false,
  "created": 1625501337000,
  "url": "<your actiTIME URL>/tasks/tasklist.do?customerId=50",
  "allowedActions": {
    "canModify": true,
    "canDelete": true
  },
  "description": null
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger

Delete Customer

Use the following request to delete a customer with given ID with all its projects and tasks (including all time tracked for it by users):

DELETE/customers/{id}

Additionally to the customer ID, the request can include the ‘revokeApprovedWeeks’ parameter that defines how weeks’ approval statuses should be affected by deletion. Time-track approval for affected weeks can be kept or revoked.

Required Permissions

To be able to delete a customer, the authorized user should have:

  • the ‘Manage Scope of Work’ permission;
  • access to this customer in Scope of Work;

The authorized user also needs permissions that allow them to delete all time tracked for tasks of this customer. This means that the following restrictions are additionally applied:

  • if time-track of other users for the customer’s tasks needs to be deleted, the authorized user should have the ‘Modify & Approve Other Users’ Time-Track’ permission and have these users in assigned team;
  • if time-track for the customer’s tasks on locked days needs to be deleted, the authorized user should have the ‘Lock Time-Track for Any User’ permission.

Example Request:

curl -X DELETE "&ltactiTIME URL&gt/api/v1/customers/4?revokeApprovedWeeks=true" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response

The 204 status code is returned if the operation is successful. Response body is empty.

If the operation has failed, an error code is returned.

For example, the 403 error code is returned when the operation has failed due to the lack of a necessary permission:

{
  "key": "api.error.cannot_delete_because_cannot_modify_time",
  "message": "Cannot delete the object as authorized user cannot modify time-track of some other users who tracked time"
}

More info on using this request is available in Swagger at the following URL:
<your actiTIME URL>/api/v1/swagger