Skip to content

entries.md

Latest commit

 

History

History
259 lines (193 loc) · 7.63 KB

entries.md

File metadata and controls

259 lines (193 loc) · 7.63 KB

Time entries

Getting time entries

You can list timesheet entries by making a GET request to:

  • /api/entries?where=project_id=[PROJECT_ID] for a list of time entries from a project
  • /api/entries?where=task_id=[TASK_ID] for a list of time entries for a task
  • /api/entries?where=user_id=[USER_ID] for a list of time entries for a user
  • /api/entries?where=client_id=[CLIENT_ID] for a list of time entries for a client
  • /api/entries?where=time_interval in ("2014-12-01T00:00:00Z","2015-01-01T00:00:00Z") for a list of time entries between Dec 1st, 2014 and Jan 1st, 2015.

Example of response:

{
  "entries": [
     {
        "id": 15200864,
        "task_id": 241184,
        "user_id": 1563,
        "start_time": "2014-12-11T09:30:00Z",
        "end_time": "2014-12-11T10:15:00Z",
        "description": "",
        "added_manually": true,
        "invoice_item_id": null,
        "billed": false,
        "is_bulk": false,
        "project_id": 28934,
        "created_on": "2014-12-12T14:42:49Z",
        "updated_on": "2014-12-12T14:42:49Z",
        "duration": 2700
     },
     {
        "id": 12186606,
        "task_id": 2093082,
        "user_id": 1563,
        "description": "",
        "added_manually": false,
        "invoice_item_id": null,
        "billed": false,
        "is_bulk": true,
        "project_id": 347452,
        "created_on": "2014-10-21T09:07:39Z",
        "updated_on": "2014-10-21T09:07:39Z",
        "duration": 21600,
        "date": "2014-10-21"
     }
  ]
}

You can also include related content when listing entries.

Getting a time entry

To get the time entry info, make a GET request to:

  • /api/entries/[ENTRY_ID]

Example response:

{
  "entries": [
     {
        "id": 15200864,
        "task_id": 241184,
        "user_id": 1563,
        "start_time": "2014-12-11T09:30:00Z",
        "end_time": "2014-12-11T10:15:00Z",
        "description": "",
        "added_manually": true,
        "invoice_item_id": null,
        "billed": false,
        "is_bulk": false,
        "project_id": 28934,
        "created_on": "2014-12-12T14:42:49Z",
        "updated_on": "2014-12-12T14:42:49Z",
        "duration": 2700
     }
  ]
}

You can also include related content when getting a time entry.

Creating a time entry

To create a time entry, make a POST request to:

  • /api/entries

with the request body containing the new time entry info, as in the examples below:

{
   "task_id": 241184,
   "start_time": "2014-12-10T09:00:00Z",
   "end_time": "2014-12-10T10:00:00Z",
   "description": "Talked to Susan on the phone."
}

to add a time entry with a start and end time, or:

{
   "task_id": 241184,
   "date": "2014-12-10",
   "duration": 3600,
   "description": "Talked to Peter on the phone."
}

to add a time entry with a date and duration. Duration is the length of the entry in seconds.

If successful, the response will return 201 Created. The response header Location will contain a link for the new time entry. The response body will contain the new time entry info as in the Getting a time entry section.

Required fields

When creating a time entry: task_id, (date and duration) or (start_time and end_time).

Restrictions

When creating a time entry with start_time and end_time the minimal time entry duration is 1 minute.

Updating a time entry

To update an existing time entry, make a POST or PUT request to:

  • /api/entries/[ENTRY_ID]

with the request body containing the updated info. You can send only the changed fields.

Example of request body if you want to change the duration:

{
   "duration": 7200
}

You can change the duration only for the time entries that were added with date and duration parameters.

For entries added with start_time and end_time the duration can be adjusted by updating the end_time.

The response will return 200 OK and will contain the updated time entry info as in the Getting a time entry section.

Restrictions

When updating an entry with start_time and end_time the new duration cannot be less than 1 minute.

Deleting a time entry

To delete a time entry, make a DELETE request to:

  • /api/entries/[ENTRY_ID]

If successful, the response will have a 200 OK status code.

Timer

A timer is a special kind of a time entry with the end_time not yet set.

Any user can have at most only one timer started at any time.

Starting a timer

Starting the timer for a user is the same as creating a time entry for that user with start_time and no end_time.

For example, make a POST request to:

  • /api/entries with the body:
{
    "task_id": 241184,
    "user_id": 1563,
    "description": "Running timer description",
    "start_time": "2017-06-20T09:30:00Z"
}

If another timer is already running for that user, the request will fail with a 409 error code.

Stopping a timer

Stopping the timer is the same as updating the timer's end_time with a valid date and time value.

For example, make a PUT request to:

  • /api/entries/[TIMER_ID] with the body:
{
    "end_time": "2017-06-20T15:00:00Z",
    "description": "Final time entry description"
}

Same restrictions as for time entries apply for timers. You cannot stop a timer if the final duration is less than a minute. To stop the timer in this case, make a DELETE request and delete the timer.

Listing running timers

To get the running timer of any particular user, make a GET request to:

  • /api/entries?where=user_id=[USER_ID] and end_time=null

The time entry object

A time entry object has the following attributes:

Attribute Type Description
id integer (read-only) Unique entry identifier
project_id integer (read-only) Project id
task_id integer Id of the task for which the time is added
user_id integer Id of the user for whom the time is added
is_bulk boolean If true the entry was added with date and duration, false if entry was added with start_time and end_time.
start_time datetime Date and time when the time entry started. Note: start_time and end_time are not present for entries with date and duration.
end_time datetime Date and time when the time entry ended
date date Date when the time entry was added. Note: date and duration are not present for entries with start_time and end_time.
duration integer Time entry duration in seconds
description text Time entry description
added_manually boolean If false the entry was added using a timer (using start/stop in Paymo Widget).
billed boolean If true the entry is billed. Time for the entry was added into an invoice.
invoice_item_id integer Id of the invoice item if the entry was billed (added into an invoice).
created_on datetime (read-only) Date and time when the entry was created
updated_on datetime (read-only) Date and time when the entry was last updated

Dependent objects

The following object types can be used in includes:

Object type Include key Relationship
Task task parent
Invoice item invoiceitem parent
User user parent