Skip to main content

Timesheets API

Endpoints for managing weekly timesheets and individual time entries.

List My Timesheets​

Returns timesheets owned by the current user.

GET /timesheets?status={status}&limit={limit}

Query Parameters:

  • status (optional): Filter by Pending, Submitted, Approved, or Rejected
  • limit (optional): Maximum results (default 50)

Response: 200 OK

{
  "data": [
    {
      "id": 42,
      "employee": 5,
      "date_start": "2026-04-05",
      "date_end": "2026-04-11",
      "status": "Pending",
      "total_time": "32:30",
      "total_minutes": 1950
    }
  ],
  "total": 10,
  "page": 1,
  "nextPage": null
}

Create Current Week Timesheet​

Creates a timesheet for the current week (Sunday–Saturday). If one already exists, the existing one is returned.

POST /timesheets/create-current

Response: 201 Created (newly created) or 200 OK (already exists)

{
  "timesheet": {
    "id": 43,
    "employee": 5,
    "date_start": "2026-04-05",
    "date_end": "2026-04-11",
    "status": "Pending",
    "days": [
      {"date": "2026-04-05", "display": "(Sun) 05 Apr"},
      {"date": "2026-04-06", "display": "(Mon) 06 Apr"}
    ]
  },
  "created": true
}

Create Previous Week Timesheet​

Creates a timesheet for the week before the reference timesheet.

POST /timesheets/{timesheetId}/create-previous

Response: 201 Created or 200 OK if the previous week's timesheet already exists.

Create Next Week Timesheet​

Creates a timesheet for the week after the reference timesheet.

POST /timesheets/{timesheetId}/create-next

Response: 201 Created or 200 OK if the next week's timesheet already exists.

Get Timesheet Details​

Returns a single timesheet with all of its time entries.

GET /timesheets/{timesheetId}

Response: 200 OK

{
  "timesheet": {
    "id": 42,
    "date_start": "2026-04-05",
    "date_end": "2026-04-11",
    "status": "Pending",
    "total_time": "16:30",
    "total_minutes": 990,
    "days": [
      {"date": "2026-04-05", "display": "(Sun) 05 Apr"}
    ]
  },
  "entries": [
    {
      "id": 156,
      "timesheet": 42,
      "project": {"type": "Project", "id": 3, "display": "Mobile App Development"},
      "date_start": "2026-04-06 09:00:00",
      "date_end": "2026-04-06 17:30:00",
      "details": "Implemented timesheet API",
      "duration_minutes": 510,
      "duration_hours": 8.5
    }
  ],
  "employee": {
    "id": 5,
    "name": "John Smith"
  }
}

Submit Timesheet for Approval​

Submits a timesheet for supervisor approval. If the user is an admin without a supervisor, the timesheet is auto-approved.

POST /timesheets/{timesheetId}/submit

Response: 200 OK

{
  "message": "Timesheet Submitted",
  "timesheet": {
    "id": 42,
    "status": "Submitted",
    "total_time": "40:00"
  }
}

Add Time Entry​

Adds a new time entry to a timesheet. The date must fall within the timesheet period.

POST /timesheets/{timesheetId}/entries

Request Body:

{
  "date": "2026-04-07",
  "start_time": "09:00:00",
  "end_time": "17:30:00",
  "project": 3,
  "details": "Implemented new API endpoints"
}

Required Fields: date, start_time, end_time

Response: 201 Created

Error Response: 400 Bad Request for invalid times or dates outside the timesheet period. Cannot add entries to approved timesheets.

Update Time Entry​

Updates an existing time entry. Cannot modify entries in approved timesheets.

POST /timesheets/entries/{entryId}/update

Request Body: Any subset of date, start_time, end_time, project, details.

Response: 200 OK

Delete Time Entry​

Deletes a time entry. Cannot delete entries from approved timesheets.

POST /timesheets/entries/{entryId}/delete

Response: 200 OK

Get Direct Reports' Timesheets​

Returns timesheets from employees who report to the current user. Use for managers reviewing their team's timesheets.

GET /timesheets/direct-reports?status={status}&limit={limit}

Response: 200 OK

{
  "data": [
    {
      "id": 44,
      "employee": 8,
      "employee_name": "Jane Doe",
      "date_start": "2026-04-05",
      "date_end": "2026-04-11",
      "status": "Submitted",
      "total_time": "42:15"
    }
  ],
  "total": 5,
  "page": 1,
  "nextPage": null
}

Get Pending Timesheets for Approval​

Convenience endpoint that returns timesheets with Submitted status from direct reports.

GET /timesheets/direct-reports/pending

Response: 200 OK

Approve Timesheet​

Approves a subordinate's submitted timesheet. Only supervisors or admins can approve.

POST /timesheets/{timesheetId}/approve

Response: 200 OK

{
  "message": "Timesheet Approved",
  "timesheet": {
    "id": 44,
    "status": "Approved",
    "total_time": "42:15"
  }
}

Error Response: 403 Forbidden if not the supervisor.

Reject Timesheet​

Rejects a subordinate's submitted timesheet. The employee can resubmit after corrections.

POST /timesheets/{timesheetId}/reject

Response: 200 OK

Get Available Projects​

Returns projects available for time entries. Returns only assigned projects unless the "Make All Projects Available to Employees" setting is enabled.

GET /timesheets/projects

Response: 200 OK

{
  "data": [
    {"id": 1, "name": "Website Redesign"},
    {"id": 3, "name": "Mobile App Development"}
  ]
}

Timesheet Status Values​

  • Pending: Draft, owner can still edit entries
  • Submitted: Awaiting supervisor approval
  • Approved: Approved by supervisor; entries are locked
  • Rejected: Rejected by supervisor; owner can correct and resubmit