API: Time Entries

Actions

Link Description Condition
updateImmediately Directly perform edits on this time entry Permission: ‘edit time entries’ or ‘edit own time entries’ if the time entry belongs to the user
update Form endpoint that aids in preparing and performing edits on a TimeEntry Permission: ‘edit time entries’ or ‘edit own time entries’ if the time entry belongs to the user
delete Delete this time entry Permission: ‘edit time entries’ or ‘edit own time entries’ if the time entry belongs to the user

Linked Properties

Link Description Type Constraints Supported operations Condition
self This time entry TimeEntry not null READ  
project The project the time entry is bundled in. The project might be different from the work package’s project once the workPackage is moved. Project not null READ / WRITE  
workPackage The work package the time entry is created on WorkPackage   READ / WRITE  
user The user the time entry tracks expenditures for User not null  READ  
activity The time entry activity the time entry is categorized as TimeEntriesActivity not null READ / WRITE  

Depending on custom fields defined for time entries, additional links might exist.

Time entries are either linked to a work package or to a project. If they are linked to a project, the work package reference is empty. If they are linked to a work package, the project reference is filled up automatically to point to the work package’s project.

Local Properties

Property Description Type Constraints Supported operations Condition
id Time entries’ id Integer x > 0 READ  
comment A text provided by the user detailing the time entry String max 255 characters READ / WRITE  
spentOn The date the expenditure is booked for Date   READ / WRITE  
hours The time quantifying the expenditure Time   READ / WRITE  
createdAt The time the time entry was created DateTime   READ  
updatedAt The time the time entry was last updated DateTime   READ  

Depending on custom fields defined for time entries, additional properties might exist.

Methods

List time entries

Lists time entries. The time entries returned depend on the filters provided and also on the permission of the requesting user.

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:

  • id: Sort by primary key

  • hours: Sort by logged hours

  • spent_on: Sort by spent on date

  • created_at: Sort by time entry creation datetime

  • updated_at: Sort by the time the time entry was updated last

Default:
["spent_on", "asc"]

Example:
[["spent_on", "asc"]]

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • work_package: Filter time entries by work package

  • project: Filter time entries by project

  • user: Filter time entries by users

  • spent_on: Filter time entries by spent on date

  • created_at: Filter time entries by creation datetime

  • updated_at: Filter time entries by the last time they where updated

  • activity: Filter time entries by time entry activity

Example:
[{ "work_package": { "operator": "=", "values": ["1", "2"] } }, { "project": { "operator": "=", "values": ["1"] } }]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "activity": {
            "href": "/api/v3/time_entries/activities/18",
            "title": "Some time entry activity"
          },
          "delete": {
            "href": "/api/v3/time_entries/1",
            "method": "delete"
          },
          "project": {
            "href": "/api/v3/projects/1",
            "title": "Some project"
          },
          "self": {
            "href": "/api/v3/time_entries/1"
          },
          "updateImmediately": {
            "href": "/api/v3/time_entries/1",
            "method": "patch"
          },
          "user": {
            "href": "/api/v3/users/2",
            "title": "Some user"
          },
          "workPackage": {
            "href": "/api/v3/work_packages/1",
            "title": "Some work package"
          }
        },
        "_type": "TimeEntry",
        "comment": {
          "format": "plain",
          "html": "<p>Some comment</p>",
          "raw": "Some comment"
        },
        "createdAt": "2015-03-20T12:56:56Z",
        "hours": "PT5H",
        "id": 5,
        "spentOn": "2015-03-20",
        "updatedAt": "2015-03-20T12:56:56Z"
      },
      {
        "_links": {
          "activity": {
            "href": "/api/v3/time_entries/activities/14",
            "title": "some other time entry activity"
          },
          "project": {
            "href": "/api/v3/projects/42",
            "title": "Some other project"
          },
          "self": {
            "href": "/api/v3/time_entries/2"
          },
          "user": {
            "href": "/api/v3/users/6",
            "title": "Some other project"
          },
          "workPackage": {
            "href": "/api/v3/work_packages/541",
            "title": "Some other work package"
          }
        },
        "_type": "TimeEntry",
        "comment": {
          "format": "plain",
          "html": "<p>Another comment</p>",
          "raw": "Another comment"
        },
        "createdAt": "2015-03-20T12:56:56Z",
        "hours": "PT7H",
        "id": 10,
        "spentOn": "2015-03-21",
        "updatedAt": "2015-03-20T12:56:56Z"
      }
    ]
  },
  "_links": {
    "changeSize": {
      "href": "/api/v3/time_entries?offset=1&pageSize=%7Bsize%7D",
      "templated": true
    },
    "createTimeEntry": {
      "href": "/api/v3/time_entries/form",
      "method": "post"
    },
    "createTimeEntryImmediately": {
      "href": "/api/v3/time_entries",
      "method": "post"
    },
    "jumpTo": {
      "href": "/api/v3/time_entries?offset=%7Boffset%7D&pageSize=2",
      "templated": true
    },
    "nextByOffset": {
      "href": "/api/v3/time_entries?offset=2&pageSize=2"
    },
    "self": {
      "href": "/api/v3/time_entries?offset=1&pageSize=2"
    }
  },
  "_type": "Collection",
  "count": 2,
  "offset": 1,
  "pageSize": 2,
  "total": 39
}

List_time_entriesModel

{
  "type": "object",
  "example": {
    "_type": "Collection",
    "total": 39,
    "count": 2,
    "pageSize": 2,
    "offset": 1,
    "_embedded": {
      "elements": [
        {
          "_type": "TimeEntry",
          "id": 5,
          "comment": {
            "format": "plain",
            "raw": "Some comment",
            "html": "<p>Some comment</p>"
          },
          "spentOn": "2015-03-20",
          "hours": "PT5H",
          "createdAt": "2015-03-20T12:56:56Z",
          "updatedAt": "2015-03-20T12:56:56Z",
          "_links": {
            "self": {
              "href": "/api/v3/time_entries/1"
            },
            "updateImmediately": {
              "href": "/api/v3/time_entries/1",
              "method": "patch"
            },
            "delete": {
              "href": "/api/v3/time_entries/1",
              "method": "delete"
            },
            "project": {
              "href": "/api/v3/projects/1",
              "title": "Some project"
            },
            "workPackage": {
              "href": "/api/v3/work_packages/1",
              "title": "Some work package"
            },
            "user": {
              "href": "/api/v3/users/2",
              "title": "Some user"
            },
            "activity": {
              "href": "/api/v3/time_entries/activities/18",
              "title": "Some time entry activity"
            }
          }
        },
        {
          "_type": "TimeEntry",
          "id": 10,
          "comment": {
            "format": "plain",
            "raw": "Another comment",
            "html": "<p>Another comment</p>"
          },
          "spentOn": "2015-03-21",
          "hours": "PT7H",
          "createdAt": "2015-03-20T12:56:56Z",
          "updatedAt": "2015-03-20T12:56:56Z",
          "_links": {
            "self": {
              "href": "/api/v3/time_entries/2"
            },
            "project": {
              "href": "/api/v3/projects/42",
              "title": "Some other project"
            },
            "workPackage": {
              "href": "/api/v3/work_packages/541",
              "title": "Some other work package"
            },
            "user": {
              "href": "/api/v3/users/6",
              "title": "Some other project"
            },
            "activity": {
              "href": "/api/v3/time_entries/activities/14",
              "title": "some other time entry activity"
            }
          }
        }
      ]
    },
    "_links": {
      "self": {
        "href": "/api/v3/time_entries?offset=1&pageSize=2"
      },
      "jumpTo": {
        "href": "/api/v3/time_entries?offset=%7Boffset%7D&pageSize=2",
        "templated": true
      },
      "changeSize": {
        "href": "/api/v3/time_entries?offset=1&pageSize=%7Bsize%7D",
        "templated": true
      },
      "nextByOffset": {
        "href": "/api/v3/time_entries?offset=2&pageSize=2"
      },
      "createTimeEntry": {
        "href": "/api/v3/time_entries/form",
        "method": "post"
      },
      "createTimeEntryImmediately": {
        "href": "/api/v3/time_entries",
        "method": "post"
      }
    }
  }
}

400

Returned if the client sends invalid request parameters e.g. filters

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
  "message": [
    "Filters Invalid filter does not exist."
  ]
}

403

Returned if the client is not logged in and login is required.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to view this resource."
}

Create time entry

Creates a new time entry applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a time entries’ attributes and are accepted by the endpoint.

No parameters

201

Created

View_time_entryModel

{
  "type": "object",
  "example": {
    "_type": "TimeEntry",
    "id": 1,
    "comment": {
      "format": "plain",
      "raw": "Some text explaining why the time entry was created",
      "html": "<p>Some text explaining why the time entry was created</p>"
    },
    "spentOn": "2015-03-20",
    "hours": "PT5H",
    "createdAt": "2015-03-20T12:56:56Z",
    "updatedAt": "2015-03-20T12:56:56Z",
    "customField12": 5,
    "_embedded": {
      "project...": {
      },
      "workPackage...": {
      },
      "user...": {
      },
      "activity...": {
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/time_entries/1"
      },
      "updateImmediately": {
        "href": "/api/v3/time_entries/1",
        "method": "patch"
      },
      "delete": {
        "href": "/api/v3/time_entries/1",
        "method": "delete"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "Some project"
      },
      "workPackage": {
        "href": "/api/v3/work_packages/1",
        "title": "Some work package"
      },
      "user": {
        "href": "/api/v3/users/2",
        "title": "Some user"
      },
      "activity": {
        "href": "/api/v3/time_entries/activities/18",
        "title": "Some time entry activity"
      },
      "customField4": {
        "href": "/api/v3/users/5",
        "title": "Some other user"
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

403

Returned if the client does not have sufficient permissions.

Required permission: Log time

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "workPackage"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Work package is invalid."
}

Available projects for time entries

Gets a list of projects in which a time entry can be created in or be assigned to on update. The list contains all projects in which the user issuing the request has the necessary permissions.

No parameters

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_type": "Project..."
      },
      {
        "_type": "Project..."
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/time_entries/available_projects"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}

Available_projects_for_time_entriesModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/time_entries/available_projects"
      }
    },
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "_embedded": {
      "elements": [
        {
          "_type": "Project..."
        },
        {
          "_type": "Project..."
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: log time, edit time entries or edit own time entries in any project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

Time entry create form

No parameters

200

OK

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

403

Returned if the client does not have sufficient permissions.

Required permission: log time in any project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

View time entry schema

No parameters

200

OK

{
  "_dependencies": [

  ],
  "_links": {
    "self": {
      "href": "/api/v3/time_entries/schema"
    }
  },
  "_type": "Schema",
  "activity": {
    "_links": {
    },
    "hasDefault": true,
    "location": "_links",
    "name": "Activity",
    "required": true,
    "type": "TimeEntriesActivity",
    "writable": true
  },
  "createdAt": {
    "hasDefault": false,
    "name": "Created on",
    "options": {
    },
    "required": true,
    "type": "DateTime",
    "writable": false
  },
  "customField29": {
    "hasDefault": false,
    "name": "sfsdfsdfsdfsdfdsf",
    "options": {
      "rtl": null
    },
    "required": false,
    "type": "String",
    "writable": true
  },
  "hours": {
    "hasDefault": false,
    "name": "Hours",
    "options": {
    },
    "required": true,
    "type": "Duration",
    "writable": true
  },
  "id": {
    "hasDefault": false,
    "name": "ID",
    "options": {
    },
    "required": true,
    "type": "Integer",
    "writable": false
  },
  "project": {
    "_links": {
    },
    "hasDefault": false,
    "location": "_links",
    "name": "Project",
    "required": false,
    "type": "Project",
    "writable": true
  },
  "spentOn": {
    "hasDefault": false,
    "name": "Date",
    "options": {
    },
    "required": true,
    "type": "Date",
    "writable": true
  },
  "updatedAt": {
    "hasDefault": false,
    "name": "Updated on",
    "options": {
    },
    "required": true,
    "type": "DateTime",
    "writable": false
  },
  "user": {
    "hasDefault": false,
    "name": "User",
    "options": {
    },
    "required": true,
    "type": "User",
    "writable": false
  },
  "workPackage": {
    "_links": {
    },
    "hasDefault": false,
    "location": "_links",
    "name": "Work package",
    "required": false,
    "type": "WorkPackage",
    "writable": true
  }
}

View_time_entry_schemaModel

{
  "type": "object",
  "example": {
    "_type": "Schema",
    "_dependencies": [

    ],
    "id": {
      "type": "Integer",
      "name": "ID",
      "required": true,
      "hasDefault": false,
      "writable": false,
      "options": {
      }
    },
    "createdAt": {
      "type": "DateTime",
      "name": "Created on",
      "required": true,
      "hasDefault": false,
      "writable": false,
      "options": {
      }
    },
    "updatedAt": {
      "type": "DateTime",
      "name": "Updated on",
      "required": true,
      "hasDefault": false,
      "writable": false,
      "options": {
      }
    },
    "spentOn": {
      "type": "Date",
      "name": "Date",
      "required": true,
      "hasDefault": false,
      "writable": true,
      "options": {
      }
    },
    "hours": {
      "type": "Duration",
      "name": "Hours",
      "required": true,
      "hasDefault": false,
      "writable": true,
      "options": {
      }
    },
    "user": {
      "type": "User",
      "name": "User",
      "required": true,
      "hasDefault": false,
      "writable": false,
      "options": {
      }
    },
    "workPackage": {
      "type": "WorkPackage",
      "name": "Work package",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "location": "_links",
      "_links": {
      }
    },
    "project": {
      "type": "Project",
      "name": "Project",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "location": "_links",
      "_links": {
      }
    },
    "activity": {
      "type": "TimeEntriesActivity",
      "name": "Activity",
      "required": true,
      "hasDefault": true,
      "writable": true,
      "location": "_links",
      "_links": {
      }
    },
    "customField29": {
      "type": "String",
      "name": "sfsdfsdfsdfsdfdsf",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "options": {
        "rtl": null
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/time_entries/schema"
      }
    }
  }
}

403

Returned if the client does not have sufficient permissions to see the schema.

Required permission: log time or view time entries or edit time entries or edit own time entries on any project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

View time entry

id
integer

required path

time entry id

Example:
1

200

OK

{
  "_embedded": {
    "activity...": {
    },
    "project...": {
    },
    "user...": {
    },
    "workPackage...": {
    }
  },
  "_links": {
    "activity": {
      "href": "/api/v3/time_entries/activities/18",
      "title": "Some time entry activity"
    },
    "customField4": {
      "href": "/api/v3/users/5",
      "title": "Some other user"
    },
    "delete": {
      "href": "/api/v3/time_entries/1",
      "method": "delete"
    },
    "project": {
      "href": "/api/v3/projects/1",
      "title": "Some project"
    },
    "self": {
      "href": "/api/v3/time_entries/1"
    },
    "updateImmediately": {
      "href": "/api/v3/time_entries/1",
      "method": "patch"
    },
    "user": {
      "href": "/api/v3/users/2",
      "title": "Some user"
    },
    "workPackage": {
      "href": "/api/v3/work_packages/1",
      "title": "Some work package"
    }
  },
  "_type": "TimeEntry",
  "comment": {
    "format": "plain",
    "html": "<p>Some text explaining why the time entry was created</p>",
    "raw": "Some text explaining why the time entry was created"
  },
  "createdAt": "2015-03-20T12:56:56Z",
  "customField12": 5,
  "hours": "PT5H",
  "id": 1,
  "spentOn": "2015-03-20",
  "updatedAt": "2015-03-20T12:56:56Z"
}

View_time_entryModel

{
  "type": "object",
  "example": {
    "_type": "TimeEntry",
    "id": 1,
    "comment": {
      "format": "plain",
      "raw": "Some text explaining why the time entry was created",
      "html": "<p>Some text explaining why the time entry was created</p>"
    },
    "spentOn": "2015-03-20",
    "hours": "PT5H",
    "createdAt": "2015-03-20T12:56:56Z",
    "updatedAt": "2015-03-20T12:56:56Z",
    "customField12": 5,
    "_embedded": {
      "project...": {
      },
      "workPackage...": {
      },
      "user...": {
      },
      "activity...": {
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/time_entries/1"
      },
      "updateImmediately": {
        "href": "/api/v3/time_entries/1",
        "method": "patch"
      },
      "delete": {
        "href": "/api/v3/time_entries/1",
        "method": "delete"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "Some project"
      },
      "workPackage": {
        "href": "/api/v3/work_packages/1",
        "title": "Some work package"
      },
      "user": {
        "href": "/api/v3/users/2",
        "title": "Some user"
      },
      "activity": {
        "href": "/api/v3/time_entries/activities/18",
        "title": "Some time entry activity"
      },
      "customField4": {
        "href": "/api/v3/users/5",
        "title": "Some other user"
      }
    }
  }
}

404

Returned if the time entry does not exist or if the user does not have permission to view them.

Required permission view time entries in the project the time entry is assigned to or view own time entries for time entries belonging to the user

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

Update time entry

Updates the given time entry by applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a time entries’ attributes and are accepted by the endpoint.

id
integer

required path

Time entry id

Example:
1

200

OK

View_time_entryModel

{
  "type": "object",
  "example": {
    "_type": "TimeEntry",
    "id": 1,
    "comment": {
      "format": "plain",
      "raw": "Some text explaining why the time entry was created",
      "html": "<p>Some text explaining why the time entry was created</p>"
    },
    "spentOn": "2015-03-20",
    "hours": "PT5H",
    "createdAt": "2015-03-20T12:56:56Z",
    "updatedAt": "2015-03-20T12:56:56Z",
    "customField12": 5,
    "_embedded": {
      "project...": {
      },
      "workPackage...": {
      },
      "user...": {
      },
      "activity...": {
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/time_entries/1"
      },
      "updateImmediately": {
        "href": "/api/v3/time_entries/1",
        "method": "patch"
      },
      "delete": {
        "href": "/api/v3/time_entries/1",
        "method": "delete"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "Some project"
      },
      "workPackage": {
        "href": "/api/v3/work_packages/1",
        "title": "Some work package"
      },
      "user": {
        "href": "/api/v3/users/2",
        "title": "Some user"
      },
      "activity": {
        "href": "/api/v3/time_entries/activities/18",
        "title": "Some time entry activity"
      },
      "customField4": {
        "href": "/api/v3/users/5",
        "title": "Some other user"
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

403

Returned if the client does not have sufficient permissions.

Required permission: Edit (own) time entries, depending on what time entry is being modified.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "workPackage"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Work package is invalid."
}

Delete time entry

Permanently deletes the specified time entry.

id
integer

required path

Time entry id

Example:
1

204

Returned if the time entry was deleted successfully.

403

Returned if the client does not have sufficient permissions

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

404

Returned if the time entry does not exist or if the user does not have sufficient permissions to see the time entry.

Required permission view time entries in the project the time entry is assigned to or view own time entries for time entries belonging to the user

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

Time entry update form

id
integer

required path

Time entries activity id

Example:
1

200

OK

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}

403

Returned if the client does not have sufficient permissions to edit the time entry.

Required permission: edit time entries for every time entry of a project, or edit own time entries for time entries belonging to the user.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

404

Returned if the time entry does not exist or if the client does not have sufficient permissions to view it.

Required permission view time entries in the project the time entry is assigned to or view own time entries for time entries belonging to the user

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}