Timesheets & Time Entries

This page covers both timesheets (read-only with status updates) and time entries (full CRUD). Timesheets are automatically created to group time entries by user and week. You cannot create or delete timesheets directly -- instead, manage individual time entries and update timesheet statuses.

Timesheets

List Timesheets

Returns a paginated list of timesheets.

GET /api/v1/timesheets

Required Scope: timesheets:read

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page, 1-100 (default: 25)
`search`	string	Search timesheets by keyword
`sort_by`	string	Field to sort by
`sort_direction`	string	`asc` or `desc` (default: `desc`)
`start_date`	string	Filter by start date (YYYY-MM-DD)
`end_date`	string	Filter by end date (YYYY-MM-DD)
`user_id`	string	Filter by user UUID
`status`	string	Filter by status: `draft`, `pending`, `approved`, or `rejected`

curl "https://app.bluesuite.com/api/v1/timesheets?status=pending&user_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer wk_abc123.your_api_key"

{
  "success": true,
  "data": [
    {
      "id": 1,
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "pending",
      "start_date": "2025-03-10",
      "end_date": "2025-03-16",
      "total_time": 40.0
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_pages": 1
  }
}

Get Timesheet

Returns a single timesheet with expanded details (time entries, user info, etc.).

GET /api/v1/timesheets/:id

Required Scope: timesheets:read

curl https://app.bluesuite.com/api/v1/timesheets/1 \
  -H "Authorization: Bearer wk_abc123.your_api_key"

{
  "success": true,
  "data": {
    "id": 1,
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending",
    "start_date": "2025-03-10",
    "end_date": "2025-03-16",
    "total_time": 40.0,
    "time_entries": [
      {
        "id": 10,
        "start_date": "2025-03-10",
        "end_date": "2025-03-10",
        "start_time": "08:00",
        "end_time": "16:00",
        "total_time": 8.0,
        "description": "Window cleaning - 123 Main St"
      }
    ]
  }
}

Update Timesheet Status

Updates the status of a timesheet.

PUT /api/v1/timesheets/:id/status

Required Scope: timesheets:write

Request Body:

Field	Type	Required	Description
`status`	string	Yes	One of: `draft`, `pending`, `approved`, `rejected`

curl -X PUT https://app.bluesuite.com/api/v1/timesheets/1/status \
  -H "Authorization: Bearer wk_abc123.your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "approved" }'

{
  "success": true,
  "data": {
    "id": 1,
    "status": "approved"
  }
}

Time Entries

List Time Entries

Returns a paginated list of time entries.

GET /api/v1/time-entries

Required Scope: timesheets:read

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page, 1-100 (default: 25)
`search`	string	Search time entries by keyword
`sort_by`	string	Field to sort by
`sort_direction`	string	`asc` or `desc` (default: `desc`)
`start_date`	string	Filter entries starting on or after this date (YYYY-MM-DD)
`end_date`	string	Filter entries ending on or before this date (YYYY-MM-DD)
`user_id`	string	Filter by user UUID
`job_id`	integer	Filter by job ID
`request_id`	integer	Filter by request ID
`quote_id`	integer	Filter by quote ID

curl "https://app.bluesuite.com/api/v1/time-entries?start_date=2025-03-10&end_date=2025-03-16&job_id=10" \
  -H "Authorization: Bearer wk_abc123.your_api_key"

{
  "success": true,
  "data": [
    {
      "id": 10,
      "start_date": "2025-03-10",
      "end_date": "2025-03-10",
      "start_time": "08:00",
      "end_time": "16:00",
      "total_time": 8.0,
      "description": "Window cleaning - 123 Main St",
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "job_id": 10
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_pages": 1
  }
}

Create Time Entry

Creates a new time entry.

POST /api/v1/time-entries

Required Scope: timesheets:write

Request Body:

Field	Type	Required	Description
`start_date`	string	Yes	Start date (YYYY-MM-DD)
`end_date`	string	Yes	End date (YYYY-MM-DD)
`start_time`	string	No	Start time (HH:MM, 24-hour format)
`end_time`	string	No	End time (HH:MM, 24-hour format)
`total_time`	number	No	Total hours worked (default: 0)
`description`	string	No	Description of work performed
`user_id`	string (UUID)	No	User who performed the work (defaults to the API key creator)
`job_id`	integer	No	Associated job ID
`request_id`	integer	No	Associated request ID
`quote_id`	integer	No	Associated quote ID

curl -X POST https://app.bluesuite.com/api/v1/time-entries \
  -H "Authorization: Bearer wk_abc123.your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-03-12",
    "end_date": "2025-03-12",
    "start_time": "09:00",
    "end_time": "12:30",
    "total_time": 3.5,
    "description": "Gutter cleaning - 456 Oak Ave",
    "job_id": 10
  }'

{
  "success": true,
  "data": {
    "id": 15,
    "start_date": "2025-03-12",
    "end_date": "2025-03-12",
    "start_time": "09:00",
    "end_time": "12:30",
    "total_time": 3.5,
    "description": "Gutter cleaning - 456 Oak Ave",
    "job_id": 10,
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2025-03-12T12:00:00.000Z"
  }
}

Update Time Entry

Updates an existing time entry. Only include the fields you want to change.

PUT /api/v1/time-entries/:id

Required Scope: timesheets:write

Request Body: Same fields as Create Time Entry. All fields are optional.

curl -X PUT https://app.bluesuite.com/api/v1/time-entries/15 \
  -H "Authorization: Bearer wk_abc123.your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "end_time": "13:00",
    "total_time": 4.0
  }'

{
  "success": true,
  "data": {
    "id": 15,
    "start_date": "2025-03-12",
    "end_date": "2025-03-12",
    "start_time": "09:00",
    "end_time": "13:00",
    "total_time": 4.0,
    "description": "Gutter cleaning - 456 Oak Ave",
    "job_id": 10
  }
}

Delete Time Entry

Deletes a time entry.

DELETE /api/v1/time-entries/:id

Required Scope: timesheets:write

curl -X DELETE https://app.bluesuite.com/api/v1/time-entries/15 \
  -H "Authorization: Bearer wk_abc123.your_api_key"

{
  "success": true,
  "data": {
    "deleted": true
  }
}

Timesheets & Time Entries

On this page