Toggle Sidebar

Time Entries

This section describes how to add, edit and retrieve time entries logged by you and the rest of your team.

A time entry represents a certain period in time, in which a person worked on a specific task or job. Time entries must always have a start and end date and are always associated to a single person within the account. Additionally, time entries can be associated to a task, which in turns can be associated to a project, client and service.

This flexible data model allows you and your team to categorize working time spent at your company in different ways depending on your specific organizational and reporting needs.

Please note: Time entries are called "events" through the entire API.

Available Endpoints

Required Parameters

Type Parameter Description
Date start The date time when the user starts tracking the event
Date end The date time when the event was stopped
Long duration The total duration in seconds
Integer user_id A time entry is always associated to a specific user. If no user_id or task_id is passed the entry will be associated to the session user.

Optional Parameters

Type Parameter Description
String type Default: WORK
String timezone The event's timezone, e.g. 'GMT-02:00'
String notes Notes up to 5000 characters allowed
String repeat Indicates whether this is a repeating event (time entry) or not. Accepted values: [EVERY_DAY | EVERY_WEEK | EVERY_MONTH | EVERY_YEAR | CUSTOM]. Default: Null (None)
Date end_repeat The date the last repeating event (time entry) should be created on.
String frequency When choosing custom repeat you need to specify the frequency at which the event occurs: [DAILY | WEEKLY | MONTHLY | YEARLY]
Integer repeat_every The number of times the event occurs for the given frequency, e.g. every 5 weeks, every 18 days, every 2 years, etc.
Integer task_id The id of the task this event is associated to

Read-only Parameters

Type Parameter Description
Integer id
String formated_duration The duration displayed in HH:MM:SS format
Integer user_id A time entry is always associated to a specific user

JSON Object

{
    "type": "WORK",
    "start": "2017-02-08 13:25:34",
    "loc_start": "02/08/2017 01:25:34 PM",
    "end": "2017-02-08 13:27:40",
    "loc_end": "02/08/2017 01:27:40 PM",
    "duration": 126,
    "loc_duration": "00:02",
    "formated_duration": "00:02:06",
    "service": null,
    "service_id": null,
    "customer": null,
    "customer_id": null,
    "project": null,
    "project_id": null,
    "skill": null,
    "skill_id": null,
    "task": "Unnamed task",
    "task_id": 2354308,
    "task_list": null,
    "due_date": null,
    "estimated_time": null,
    "is_archived": true,
    "user": "Diego M. Wyllie",
    "user_id": 1,
    "timezone": "GMT 01:00",
    "notes": null,
    "color": null,
    "repeat": null,
    "end_repeat": null,
    "frequency": null,
    "repeat_every": null,
    "hourly_rate": null,
    "is_billable": true,
    "is_billed": false,
    "id": 8438541,
    "created_at": "2017-02-08 09:25:34",
    "updated_at": null,
    "json": null
  }

Endpoints

List Time Entries

List all account's time entries for a specific time period, filtered by an object type and id. This endpoint allows pagination in case you need to retrieve large amounts of entries.


Endpoint

https://app.trackingtime.co/api/v4/events

Parameters

Type Parameter Description Required
String filter [SERVICE | CUSTOMER | PROJECT | USER | COMPANY | TASK]. Default: USER YES
Integer id The id of the object passed as filter YES
Date from Optional date filter. Defaults to today if not entered. NO
Date to Optional date filter. Defaults to today if not entered. NO
Integer page If you want to paginate your results enter the index of the page you want (0...n) NO
Integer page_size Specifies the number of results included in one page. Default: 50 NO
String order Specifies whether the results should be ordered by start date ascending or descending. Valid values: ["asc" | "desc"]. Default: "asc" NO

Permissions

  • Admins and project managers can always view all account entries
  • Co-workers can be given permission (can_edit_time_entries) to edit time entries (own entries as well as entries they have access to)

Get Time Entry

Retrieve the unique time entry with the given id.


Endpoint

https://app.trackingtime.co/api/v4/events/:event_id

Permissions

  • Admins and project managers can always view all account entries
  • Co-workers can be given permission (can_edit_time_entries) to edit time entries (own entries as well as entries they have access to)

Add Time Entry

Add a new time entry. A time entry must be always associated to a user and have a specific duration. Optionally, a time entry can have an start and end date and be associated to a task.


Add a new time entry

Pass a user_id. The time entry is only associated to the given user.


Add a new time entry for a task

Pass a task_id and user_id.


Add a new time entry for a project

Pass a project_id and a user_id. A hidden task will be automatically created and associated to the requested project.


Endpoint

https://app.trackingtime.co/api/v4/events/add

Parameters

Type Parameter Description Required
Long duration The total event duration in seconds. YES
Integer user_id The id of the user associated to the time entry. If no user_id requested the event will be associated to the task's assignee [BACKWARDS COMPATIBILITY]. YES
Date start The date time when the user starts tracking the event YES
Date end The date time when the event was stopped YES
Integer task_id The id of the task associated to this event NO
Integer project_id The id of a project associated to this event. Use this parameter if you want to add time directly to a project without using a task. NO
String timezone The event's timezone, e.g. 'GMT-03:00' NO
String notes Notes up to 5000 characters allowed NO
String repeat Indicates whether this is a repeating event (time entry) or not. Accepted values: [EVERY_DAY | EVERY_WEEK | EVERY_MONTH | EVERY_YEAR | CUSTOM]. Default: Null (None) NO
Date end_repeat The date the last repeating event (time entry) should be created on. NO
String frequency When choosing custom repeat you need to specify the frequency at which the event occurs: [DAILY | WEEKLY | MONTHLY | YEARLY] NO
Integer repeat_every The number of times the event occurs for the given frequency, e.g. every 5 weeks, every 18 days, every 2 years, etc. NO

Permissions

  • Admins and project managers can always add time entries
  • Co-workers can be given permission (can_edit_time_entries) to edit time entries (own entries as well as entries they have access to)

Update Time Entry

Update an existing time entry in your account.


Endpoint

https://app.trackingtime.co/api/v4/events/update/:id

Parameters

Type Parameter Description Required
Integer task_id The id of the task associated to this event NO
Integer project_id The id of a project associated to this event. Use this parameter if you want to add time directly to a project without using a task. NO
Date start The date time when the user starts tracking the event NO
Date end The date time when the event was stopped YES
String timezone The event's timezone, e.g. 'GMT-03:00' NO
String notes Notes up to 5000 characters allowed NO
Boolean update_all In case of a repeating event, indicates whether to update all associated events or not. Default: false NO

Permissions

  • Admins and project managers can always add time entries
  • Co-workers can be given permission (can_edit_time_entries) to edit time entries (own entries as well as entries they have access to)

Delete Time Entry

Delete an existing time entry from your account.


Endpoint

https://app.trackingtime.co/api/v4/events/delete/:event_id

Parameters

Type Parameter Description Required
Boolean delete_all In case of a repeating event, indicates whether to delete all associated events or not. Default: false NO

Permissions

  • Admins and project managers can always delete time entries
  • Co-workers can be given permission (can_edit_time_entries) to delete time entries (own entries as well as entries they have access to)

Export Time Entries

Export a list of time entries in CSV format. The export contains all event and task parameters.


Endpoint

https://app.trackingtime.co/api/v4/events/export

Parameters

Type Attribute Description Required
String separator The character to use as separator: ; or , YES
String filter [SERVICE | CUSTOMER | PROJECT | USER | ACCOUNT | TASK]. Default: USER YES
Integer id The id of the object passed as filter YES
Date from Optional date filter NO
Date to Optional date filter NO

Response

CSV Sample File

Permissions

  • Only admins and project managers can export time entries