EmployeesGet the weekly timesheet status of employees

Get the weekly timesheet status of employees

Lists, per employee the caller may see, the timesheet status (Empty / Open / Closed / Approved) of each week in a date range.

The API form of TimeLog's timesheet status report: a manager's or payroll's overview of who has not submitted or not been approved yet. Each employee comes back once per page with their current approval manager and department and a Details list of weeks. The statuses are read from the pre-computed timesheet-status aggregation (refreshed in the background after registrations / approvals change), not computed live like GET /v1/approval/timesheets/get-status-by-period, and they are coarser: rejected weeks show as Open (or Empty), and every "submitted but not fully approved by the employee manager" state shows as Closed. Paging is per employee-WEEK row, not per employee: with the default page size of 10 a four-week range returns only two or three employees per page, an employee can be split across two pages, and TotalRecord counts rows. Ask for a large $pagesize (no maximum is enforced) and merge Details by EmployeeUserID.

Use it to:

  • Payroll cut-off dashboard: which employees still have Open or Closed weeks in the pay period.
  • Weekly reminder bot: employees with Open weeks, grouped by approval manager.

Not for:

  • Exact, real-time per-day status before exporting time — use GET /v1/approval/timesheets/get-status-by-period (live, per day, distinguishes Rejected).

Behaviour:

  • Idempotent.
  • Safe to retry.

Call first: GET /v1/user

Next: GET /v1/approval/timesheets/get-status-by-period

See also: GET /v1/approval/timesheets/get-status-range-by-nearby-week-of-year

Not yet documented: behaviour → consistency; examples (success); request → query params → description.

curl -X GET "https://app3.timelog.com/your-account/api/v1/timesheet-status/weekly?startDate=2024-12-25&endDate=2024-12-25&legalEntityId=123&departmentId=123&approverId=123&userId=123&$page=1&$pagesize=10" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
{
  "Properties": {
    "TotalRecord": "example_string",
    "TotalPage": "example_string",
    "PageNumber": "example_string"
  },
  "Entities": [
    {
      "Properties": {
        "EmployeeUserID": 123,
        "Initials": "example_string",
        "DisplayName": "John Doe",
        "ManagerInitials": "example_string",
        "ManagerDisplayName": "John Doe",
        "EmployeeDepartmentName": "John Doe",
        "AggregationType": 42,
        "ShowSendEmailRequest": true,
        "Details": [
          {
            "WeekNumber": 42,
            "TimesheetStatus": "Empty",
            "StartDate": "2024-12-25T10:00:00Z",
            "EndDate": "2024-12-25T10:00:00Z"
          }
        ]
      },
      "Links": [
        {
          "Href": "example_string",
          "Rel": "example_string"
        }
      ],
      "Actions": [
        {}
      ]
    }
  ],
  "Links": [
    {
      "Href": "example_string",
      "Rel": "example_string"
    }
  ]
}
GET
/v1/timesheet-status/weekly
GET
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.
query
startDatestring
Required

First day of the range (time part dropped). Weeks overlapping the range are returned whole. Omitted -> 404 action-not-matched. Date only — no time component.

Format: date
query
endDatestring
Required

Last day of the range (time part dropped). Not checked against startDate. Date only — no time component.

Format: date
query
legalEntityIdinteger

Only employees of this legal entity. 0 / omitted = no filter. Filters on employee's legal entity (eq).

Format: int32
query
departmentIdinteger

Only employees of this department OR any of its sub-departments. 0 / omitted = no filter. Filters on employee's department (eq).

Format: int32
query
approverIdinteger

Only employees whose current approval manager has this EMPLOYEE ID — not a user ID, unlike userId. 0 / omitted = no filter. Filters on employee's current approval manager (eq).

Format: int32
query
userIdinteger

Only this employee (user ID). 0 / omitted = no filter. Filters on TimesheetStatusRead.EmployeeUserID (eq).

Format: int32
query
$pageinteger

Page number — of employee-week rows.

query
$pagesizeinteger

Employee-week ROWS per page, not employees. No maximum enforced.

Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp).

The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user.

Not yet documented: how to obtain a token.

Not yet documented: token lifetime.

Query Parameters

startDatestring
Required

First day of the range (time part dropped). Weeks overlapping the range are returned whole. Omitted -> 404 action-not-matched.

Date only — no time component.

endDatestring
Required

Last day of the range (time part dropped). Not checked against startDate.

Date only — no time component.

legalEntityIdinteger

Only employees of this legal entity. 0 / omitted = no filter.

Filters on employee's legal entity (eq).

departmentIdinteger

Only employees of this department OR any of its sub-departments. 0 / omitted = no filter.

Filters on employee's department (eq).

approverIdinteger

Only employees whose current approval manager has this EMPLOYEE ID — not a user ID, unlike userId. 0 / omitted = no filter.

Filters on employee's current approval manager (eq).

userIdinteger

Only this employee (user ID). 0 / omitted = no filter.

Filters on TimesheetStatusRead.EmployeeUserID (eq).

$pageinteger

Page number — of employee-week rows.

$pagesizeinteger

Employee-week ROWS per page, not employees. No maximum enforced.

Responses

Propertiesobject

Paging values. They are returned as STRINGS, for example "TotalRecord": "12".

Entitiesarray

Omitted (not []) when the list is empty.

Linksarray