Time API

REST endpoints for time in ServFlo: 17 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

Operation	Endpoint	Risk
Labour time on a job	`GET /organizations/{organizationId}/jobs/{jobId}/time`	`read`
Your clock: clocked in, on a break, today's time	`GET /organizations/{organizationId}/time/clock`	`read`
Clock in	`POST /organizations/{organizationId}/time/clock-in`	`write`
Clock out	`POST /organizations/{organizationId}/time/clock-out`	`write`
Start a break	`POST /organizations/{organizationId}/time/break/start`	`write`
End a break	`POST /organizations/{organizationId}/time/break/end`	`write`
Start non-job time	`POST /organizations/{organizationId}/time/activity/start`	`write`
End non-job time	`POST /organizations/{organizationId}/time/activity/end`	`write`
List time entries	`GET /organizations/{organizationId}/time-entries`	`read`
Add a time entry by hand	`POST /organizations/{organizationId}/time-entries`	`write`
Edit a time entry	`PATCH /organizations/{organizationId}/time-entries/{entryId}`	`write`
Delete a time entry	`DELETE /organizations/{organizationId}/time-entries/{entryId}`	`sensitive`
Everyone's week	`GET /organizations/{organizationId}/timesheets`	`read`
One person's week	`GET /organizations/{organizationId}/timesheets/{userId}`	`read`
Submit your week	`POST /organizations/{organizationId}/timesheets/submit`	`write`
Approve or reject a person's week	`POST /organizations/{organizationId}/timesheets/{userId}/review`	`write`
Export a week as CSV	`GET /organizations/{organizationId}/timesheets/export`	`read`

Labour time on a job

GET /organizations/{organizationId}/jobs/{jobId}/time

Job and travel minutes per person on the job, the totals, and the entries. Technicians see their own time on their own jobs. Read-only.

Permission: time.read (Owner, Admin, Dispatcher, Technician (own time)); risk read (OAuth scope servflo.read).


Permission	`time.read`
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`jobTime_get` (toolset `scheduling`)

Parameters

Name	In	Type	Required	Description
`jobId`	path	string	Yes

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/jobs/{jobId}/time" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`people`	array of object
`people[].userId`	string
`people[].name`	string or null
`people[].technician`	object or null
`people[].technician.id`	string
`people[].technician.name`	string
`people[].technician.color`	string
`people[].jobMinutes`	integer
`people[].travelMinutes`	integer
`people[].running`	boolean
`jobMinutes`	integer
`travelMinutes`	integer
`entries`	array of object
`entries[].id`	string
`entries[].organizationId`	string
`entries[].userId`	string
`entries[].technicianId`	string or null
`entries[].jobId`	string or null
`entries[].kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`entries[].activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`entries[].startedAt`	string (date-time)
`entries[].endedAt`	string (date-time) or null
`entries[].note`	string or null
`entries[].source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`entries[].status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`entries[].editReason`	string or null
`entries[].editedByUserId`	string or null
`entries[].approvedByUserId`	string or null
`entries[].approvedAt`	string (date-time) or null
`entries[].createdAt`	string (date-time)
`entries[].updatedAt`	string (date-time)
`entries[].job`	object or null
`entries[].job.id`	string
`entries[].job.identifier`	string
`entries[].technician`	object or null
`entries[].technician.id`	string
`entries[].technician.name`	string
`entries[].technician.color`	string
`entries[].userName`	string or null
`entries[].minutes`	integer	Whole minutes (a running entry counts to now).
`entries[].date`	string	The day it started, in the requested timezone.

Your clock: clocked in, on a break, today's time

GET /organizations/{organizationId}/time/clock

The caller's running entries (SHIFT, BREAK, JOB, TRAVEL) and today's minutes per kind and paid minutes, date being today in timeZone. Read-only.


Permission	`time.track.own` (Owner, Admin, Dispatcher, Technician)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`timeClock_get` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`date`	query	string	No	The day, YYYY-MM-DD. Defaults to today in the organization's timezone.
`timeZone`	query	string	No	IANA timezone days and weeks are counted in (e.g. America/Chicago). Defaults to the organization's timezone (Settings → General). Up to 100 characters.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time/clock" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`clockedIn`	boolean
`onBreak`	boolean
`activity`	enum or null	The non-job time running now, if any. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`running`	array of object
`running[].id`	string
`running[].organizationId`	string
`running[].userId`	string
`running[].technicianId`	string or null
`running[].jobId`	string or null
`running[].kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`running[].activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`running[].startedAt`	string (date-time)
`running[].endedAt`	string (date-time) or null
`running[].note`	string or null
`running[].source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`running[].status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`running[].editReason`	string or null
`running[].editedByUserId`	string or null
`running[].approvedByUserId`	string or null
`running[].approvedAt`	string (date-time) or null
`running[].createdAt`	string (date-time)
`running[].updatedAt`	string (date-time)
`running[].job`	object or null
`running[].job.id`	string
`running[].job.identifier`	string
`running[].technician`	object or null
`running[].technician.id`	string
`running[].technician.name`	string
`running[].technician.color`	string
`running[].userName`	string or null
`running[].minutes`	integer	Whole minutes (a running entry counts to now).
`running[].date`	string	The day it started, in the requested timezone.
`today`	object
`today.SHIFT`	integer
`today.JOB`	integer
`today.TRAVEL`	integer
`today.BREAK`	integer
`today.ACTIVITY`	integer
`today.paid`	integer	Paid minutes: SHIFT minus BREAK on a day with a shift, else JOB plus TRAVEL plus ACTIVITY.

Clock in

POST /organizations/{organizationId}/time/clock-in

Starts the caller's SHIFT now. Already clocked in: returns the running shift (safe to retry). Emits time.clocked_in. Returns the shift entry.


Permission	`time.track.own` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timeClock_clockIn` (toolset `team`)

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time/clock-in" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`userId`	string
`technicianId`	string or null
`jobId`	string or null
`kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`startedAt`	string (date-time)
`endedAt`	string (date-time) or null
`note`	string or null
`source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`editReason`	string or null
`editedByUserId`	string or null
`approvedByUserId`	string or null
`approvedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`job`	object or null
`job.id`	string
`job.identifier`	string
`technician`	object or null
`technician.id`	string
`technician.name`	string
`technician.color`	string
`userName`	string or null
`minutes`	integer	Whole minutes (a running entry counts to now).
`date`	string	The day it started, in the requested timezone.

Clock out

POST /organizations/{organizationId}/time/clock-out

Ends the caller's SHIFT now, and any running break, job or travel time. 409 when not clocked in. Emits time.clocked_out. Returns the shift entry.


Permission	`time.track.own` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timeClock_clockOut` (toolset `team`)

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time/clock-out" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`userId`	string
`technicianId`	string or null
`jobId`	string or null
`kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`startedAt`	string (date-time)
`endedAt`	string (date-time) or null
`note`	string or null
`source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`editReason`	string or null
`editedByUserId`	string or null
`approvedByUserId`	string or null
`approvedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`job`	object or null
`job.id`	string
`job.identifier`	string
`technician`	object or null
`technician.id`	string
`technician.name`	string
`technician.color`	string
`userName`	string or null
`minutes`	integer	Whole minutes (a running entry counts to now).
`date`	string	The day it started, in the requested timezone.

Start a break

POST /organizations/{organizationId}/time/break/start

Starts a BREAK for the caller (they must be clocked in; 409 otherwise). Already on a break: returns it. Breaks are taken off paid time.


Permission	`time.track.own` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timeClock_startBreak` (toolset `team`)

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time/break/start" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`userId`	string
`technicianId`	string or null
`jobId`	string or null
`kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`startedAt`	string (date-time)
`endedAt`	string (date-time) or null
`note`	string or null
`source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`editReason`	string or null
`editedByUserId`	string or null
`approvedByUserId`	string or null
`approvedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`job`	object or null
`job.id`	string
`job.identifier`	string
`technician`	object or null
`technician.id`	string
`technician.name`	string
`technician.color`	string
`userName`	string or null
`minutes`	integer	Whole minutes (a running entry counts to now).
`date`	string	The day it started, in the requested timezone.

End a break

POST /organizations/{organizationId}/time/break/end

Ends the caller's running BREAK (409 when not on one). Returns the break entry.


Permission	`time.track.own` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timeClock_endBreak` (toolset `team`)

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time/break/end" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`userId`	string
`technicianId`	string or null
`jobId`	string or null
`kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`startedAt`	string (date-time)
`endedAt`	string (date-time) or null
`note`	string or null
`source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`editReason`	string or null
`editedByUserId`	string or null
`approvedByUserId`	string or null
`approvedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`job`	object or null
`job.id`	string
`job.identifier`	string
`technician`	object or null
`technician.id`	string
`technician.name`	string
`technician.color`	string
`userName`	string or null
`minutes`	integer	Whole minutes (a running entry counts to now).
`date`	string	The day it started, in the requested timezone.

Start non-job time

POST /organizations/{organizationId}/time/activity/start

Starts non-job work for the caller (ACTIVITY with activity: the shop, the supply house, a meeting, training, the vehicle, paperwork or other), as ServiceTitan's non-job events. Needs a running shift (409 otherwise). Stops a break, travel or another activity; the same activity again returns the running one. Heading to or starting a job ends it. Paid time, shown per activity on the timesheet.


Permission	`time.track.own` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timeClock_startActivity` (toolset `team`)

Request body

Field	Type	Required	Description
`activity`	enum	Yes	Non-job time: SHOP, SUPPLY_HOUSE, MEETING, TRAINING, VEHICLE (fuel, service), ADMIN (paperwork) or OTHER. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`note`	string or null	No	Up to 500 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time/activity/start" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activity":"SHOP"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`userId`	string
`technicianId`	string or null
`jobId`	string or null
`kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`startedAt`	string (date-time)
`endedAt`	string (date-time) or null
`note`	string or null
`source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`editReason`	string or null
`editedByUserId`	string or null
`approvedByUserId`	string or null
`approvedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`job`	object or null
`job.id`	string
`job.identifier`	string
`technician`	object or null
`technician.id`	string
`technician.name`	string
`technician.color`	string
`userName`	string or null
`minutes`	integer	Whole minutes (a running entry counts to now).
`date`	string	The day it started, in the requested timezone.

End non-job time

POST /organizations/{organizationId}/time/activity/end

Ends the caller's running ACTIVITY (409 when none). Returns the entry.


Permission	`time.track.own` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timeClock_endActivity` (toolset `team`)

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time/activity/end" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`userId`	string
`technicianId`	string or null
`jobId`	string or null
`kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`startedAt`	string (date-time)
`endedAt`	string (date-time) or null
`note`	string or null
`source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`editReason`	string or null
`editedByUserId`	string or null
`approvedByUserId`	string or null
`approvedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`job`	object or null
`job.id`	string
`job.identifier`	string
`technician`	object or null
`technician.id`	string
`technician.name`	string
`technician.color`	string
`userName`	string or null
`minutes`	integer	Whole minutes (a running entry counts to now).
`date`	string	The day it started, in the requested timezone.

List time entries

GET /organizations/{organizationId}/time-entries

Time entries newest first, filtered by person (userId), technician, job, kind, status and days (from/to, YYYY-MM-DD in timeZone), paged with limit/offset and a total. Technicians always get only their own entries. Read-only.

Permission: time.read (Owner, Admin, Dispatcher, Technician (own time)); risk read (OAuth scope servflo.read).


Permission	`time.read`
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`timeEntries_list` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`userId`	query	string	No	Up to 200 characters.
`technicianId`	query	string	No
`jobId`	query	string	No
`kind`	query	enum	No	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`status`	query	enum	No	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`from`	query	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.
`to`	query	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.
`timeZone`	query	string	No	IANA timezone days and weeks are counted in (e.g. America/Chicago). Defaults to the organization's timezone (Settings → General). Up to 100 characters.
`limit`	query	integer	No	1–500.
`offset`	query	integer	No

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time-entries" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`items`	array of object
`items[].id`	string
`items[].organizationId`	string
`items[].userId`	string
`items[].technicianId`	string or null
`items[].jobId`	string or null
`items[].kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`items[].activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`items[].startedAt`	string (date-time)
`items[].endedAt`	string (date-time) or null
`items[].note`	string or null
`items[].source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`items[].status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`items[].editReason`	string or null
`items[].editedByUserId`	string or null
`items[].approvedByUserId`	string or null
`items[].approvedAt`	string (date-time) or null
`items[].createdAt`	string (date-time)
`items[].updatedAt`	string (date-time)
`items[].job`	object or null
`items[].job.id`	string
`items[].job.identifier`	string
`items[].technician`	object or null
`items[].technician.id`	string
`items[].technician.name`	string
`items[].technician.color`	string
`items[].userName`	string or null
`items[].minutes`	integer	Whole minutes (a running entry counts to now).
`items[].date`	string	The day it started, in the requested timezone.
`total`	integer

Add a time entry by hand

POST /organizations/{organizationId}/time-entries

Records finished time with a reason (source MANUAL): for the caller, or (office roles with time.manage) for userId or technicianId (a technician linked to an account). It may not overlap another entry of the same kind for that person (409), start in the future or run over 24 hours (400). Technicians may add only their own time, on their own jobs. Returns the entry.

Permission: time.manage (Owner, Admin, Dispatcher, Technician (own time)); risk write (OAuth scope servflo.write).


Permission	`time.manage`
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timeEntries_create` (toolset `team`)

Request body

Field	Type	Required	Description
`userId`	string	No	Whose time (office roles). Up to 200 characters.
`technicianId`	string or null	No	Whose time, by technician (must be linked).
`jobId`	string or null	No	The job worked on (JOB / TRAVEL).
`kind`	enum	Yes	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`startedAt`	string (date-time)	Yes	An instant as an ISO 8601 date-time with offset, e.g. 2026-10-05T08:30:00-05:00.
`endedAt`	string (date-time)	Yes	An instant as an ISO 8601 date-time with offset, e.g. 2026-10-05T08:30:00-05:00.
`note`	string or null	No	Up to 2000 characters.
`reason`	string	Yes	Why the entry is added or changed; kept on the entry for the approver. Up to 1000 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time-entries" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"SHIFT","startedAt":"2026-11-03T15:00:00Z","endedAt":"2026-11-03T15:00:00Z","reason":"string"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`userId`	string
`technicianId`	string or null
`jobId`	string or null
`kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`startedAt`	string (date-time)
`endedAt`	string (date-time) or null
`note`	string or null
`source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`editReason`	string or null
`editedByUserId`	string or null
`approvedByUserId`	string or null
`approvedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`job`	object or null
`job.id`	string
`job.identifier`	string
`technician`	object or null
`technician.id`	string
`technician.name`	string
`technician.color`	string
`userName`	string or null
`minutes`	integer	Whole minutes (a running entry counts to now).
`date`	string	The day it started, in the requested timezone.

Edit a time entry

PATCH /organizations/{organizationId}/time-entries/{entryId}

Changes the times, kind, job or note of an entry, with a reason kept on it. An APPROVED entry can only be changed by someone who approves timesheets (400 otherwise); any other change sends the entry back to OPEN for review. Same overlap rules as adding. Technicians: their own entries only (404 otherwise). Returns the entry.

Permission: time.manage (Owner, Admin, Dispatcher, Technician (own time)); risk write (OAuth scope servflo.write).


Permission	`time.manage`
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timeEntries_update` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`entryId`	path	string	Yes

Request body

Field	Type	Required	Description
`kind`	enum	No	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`startedAt`	string (date-time)	No	An instant as an ISO 8601 date-time with offset, e.g. 2026-10-05T08:30:00-05:00.
`endedAt`	string (date-time) or null	No	null keeps it running (only one per kind).
`jobId`	string or null	No
`note`	string or null	No	Up to 2000 characters.
`reason`	string	Yes	Why the entry is added or changed; kept on the entry for the approver. Up to 1000 characters.

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time-entries/{entryId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"string"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`userId`	string
`technicianId`	string or null
`jobId`	string or null
`kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`startedAt`	string (date-time)
`endedAt`	string (date-time) or null
`note`	string or null
`source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`editReason`	string or null
`editedByUserId`	string or null
`approvedByUserId`	string or null
`approvedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`job`	object or null
`job.id`	string
`job.identifier`	string
`technician`	object or null
`technician.id`	string
`technician.name`	string
`technician.color`	string
`userName`	string or null
`minutes`	integer	Whole minutes (a running entry counts to now).
`date`	string	The day it started, in the requested timezone.

Delete a time entry

DELETE /organizations/{organizationId}/time-entries/{entryId}

Destructive: deletes the entry. An APPROVED entry needs timesheets.approve. Technicians: their own entries only.

Permission: time.manage (Owner, Admin, Dispatcher, Technician (own time)); risk sensitive (OAuth scope servflo.sensitive).


Permission	`time.manage`
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`timeEntries_delete` (toolset `team`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

Name	In	Type	Required	Description
`entryId`	path	string	Yes

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time-entries/{entryId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`ok`	true

Everyone's week

GET /organizations/{organizationId}/timesheets

One row per person with time in the week (and every linked technician): minutes per day and kind, paid minutes, the week's approval state and whether a clock is running. Technicians get only their own row. Read-only. Open a person with GET /timesheets/{userId}.

Permission: time.read (Owner, Admin, Dispatcher, Technician (own time)); risk read (OAuth scope servflo.read).


Permission	`time.read`
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`timesheets_list` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`weekStart`	query	string	Yes	The first day (Monday) of the week, YYYY-MM-DD.
`timeZone`	query	string	No	IANA timezone days and weeks are counted in (e.g. America/Chicago). Defaults to the organization's timezone (Settings → General). Up to 100 characters.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/timesheets?weekStart=2026-11-03" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`userId`	string
`userName`	string or null
`technician`	object or null
`technician.id`	string
`technician.name`	string
`technician.color`	string
`status`	enum or null	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`entryCount`	integer
`running`	boolean
`runningSince`	string (date-time) or null	When the running clock started (the running shift, else the earliest running entry); null when nothing runs.
`days`	array of object
`days[].SHIFT`	integer
`days[].JOB`	integer
`days[].TRAVEL`	integer
`days[].BREAK`	integer
`days[].ACTIVITY`	integer
`days[].paid`	integer	Paid minutes: SHIFT minus BREAK on a day with a shift, else JOB plus TRAVEL plus ACTIVITY.
`days[].date`	string
`totals`	object
`totals.SHIFT`	integer
`totals.JOB`	integer
`totals.TRAVEL`	integer
`totals.BREAK`	integer
`totals.ACTIVITY`	integer
`totals.paid`	integer	Paid minutes: SHIFT minus BREAK on a day with a shift, else JOB plus TRAVEL plus ACTIVITY.
`byJob`	array of object
`byJob[].jobId`	string
`byJob[].minutes`	integer

One person's week

GET /organizations/{organizationId}/timesheets/{userId}

A person's entries for the week with totals per day, for the week and per job, and the week's approval state. userId from GET /timesheets (or your own id from GET /users/me). Technicians: their own only (404 otherwise). Read-only.

Permission: time.read (Owner, Admin, Dispatcher, Technician (own time)); risk read (OAuth scope servflo.read).


Permission	`time.read`
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`timesheets_get` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`userId`	path	string	Yes	Up to 200 characters.
`weekStart`	query	string	Yes	The first day (Monday) of the week, YYYY-MM-DD.
`timeZone`	query	string	No	IANA timezone days and weeks are counted in (e.g. America/Chicago). Defaults to the organization's timezone (Settings → General). Up to 100 characters.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/timesheets/{userId}?weekStart=2026-11-03" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`userId`	string
`userName`	string or null
`weekStart`	string
`timeZone`	string
`status`	enum or null	The week's state; null when empty. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`entries`	array of object
`entries[].id`	string
`entries[].organizationId`	string
`entries[].userId`	string
`entries[].technicianId`	string or null
`entries[].jobId`	string or null
`entries[].kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`entries[].activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`entries[].startedAt`	string (date-time)
`entries[].endedAt`	string (date-time) or null
`entries[].note`	string or null
`entries[].source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`entries[].status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`entries[].editReason`	string or null
`entries[].editedByUserId`	string or null
`entries[].approvedByUserId`	string or null
`entries[].approvedAt`	string (date-time) or null
`entries[].createdAt`	string (date-time)
`entries[].updatedAt`	string (date-time)
`entries[].job`	object or null
`entries[].job.id`	string
`entries[].job.identifier`	string
`entries[].technician`	object or null
`entries[].technician.id`	string
`entries[].technician.name`	string
`entries[].technician.color`	string
`entries[].userName`	string or null
`entries[].minutes`	integer	Whole minutes (a running entry counts to now).
`entries[].date`	string	The day it started, in the requested timezone.
`days`	array of object
`days[].SHIFT`	integer
`days[].JOB`	integer
`days[].TRAVEL`	integer
`days[].BREAK`	integer
`days[].ACTIVITY`	integer
`days[].paid`	integer	Paid minutes: SHIFT minus BREAK on a day with a shift, else JOB plus TRAVEL plus ACTIVITY.
`days[].date`	string
`totals`	object
`totals.SHIFT`	integer
`totals.JOB`	integer
`totals.TRAVEL`	integer
`totals.BREAK`	integer
`totals.ACTIVITY`	integer
`totals.paid`	integer	Paid minutes: SHIFT minus BREAK on a day with a shift, else JOB plus TRAVEL plus ACTIVITY.
`byJob`	array of object
`byJob[].jobId`	string
`byJob[].minutes`	integer
`byJob[].identifier`	string or null

Submit your week

POST /organizations/{organizationId}/timesheets/submit

Submits the caller's finished OPEN or REJECTED entries for the week for approval (SUBMITTED). Refused while a clock is running (409) or when there is nothing to submit (400). Emits timesheet.submitted. Returns the week.


Permission	`time.track.own` (Owner, Admin, Dispatcher, Technician)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timesheets_submit` (toolset `team`)

Request body

Field	Type	Required	Description
`weekStart`	string	Yes	The first day (Monday) of the week, YYYY-MM-DD.
`timeZone`	string	No	IANA timezone days and weeks are counted in (e.g. America/Chicago). Defaults to the organization's timezone (Settings → General). Up to 100 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/timesheets/submit" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"weekStart":"2026-11-03"}'

Response

200: the answer's fields

Field	Type	Description
`userId`	string
`userName`	string or null
`weekStart`	string
`timeZone`	string
`status`	enum or null	The week's state; null when empty. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`entries`	array of object
`entries[].id`	string
`entries[].organizationId`	string
`entries[].userId`	string
`entries[].technicianId`	string or null
`entries[].jobId`	string or null
`entries[].kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`entries[].activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`entries[].startedAt`	string (date-time)
`entries[].endedAt`	string (date-time) or null
`entries[].note`	string or null
`entries[].source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`entries[].status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`entries[].editReason`	string or null
`entries[].editedByUserId`	string or null
`entries[].approvedByUserId`	string or null
`entries[].approvedAt`	string (date-time) or null
`entries[].createdAt`	string (date-time)
`entries[].updatedAt`	string (date-time)
`entries[].job`	object or null
`entries[].job.id`	string
`entries[].job.identifier`	string
`entries[].technician`	object or null
`entries[].technician.id`	string
`entries[].technician.name`	string
`entries[].technician.color`	string
`entries[].userName`	string or null
`entries[].minutes`	integer	Whole minutes (a running entry counts to now).
`entries[].date`	string	The day it started, in the requested timezone.
`days`	array of object
`days[].SHIFT`	integer
`days[].JOB`	integer
`days[].TRAVEL`	integer
`days[].BREAK`	integer
`days[].ACTIVITY`	integer
`days[].paid`	integer	Paid minutes: SHIFT minus BREAK on a day with a shift, else JOB plus TRAVEL plus ACTIVITY.
`days[].date`	string
`totals`	object
`totals.SHIFT`	integer
`totals.JOB`	integer
`totals.TRAVEL`	integer
`totals.BREAK`	integer
`totals.ACTIVITY`	integer
`totals.paid`	integer	Paid minutes: SHIFT minus BREAK on a day with a shift, else JOB plus TRAVEL plus ACTIVITY.
`byJob`	array of object
`byJob[].jobId`	string
`byJob[].minutes`	integer
`byJob[].identifier`	string or null

Approve or reject a person's week

POST /organizations/{organizationId}/timesheets/{userId}/review

decision: APPROVED approves every finished entry of the person's week (recording who and when); REJECTED sends them back to be fixed and resubmitted. Approved entries can then only be edited by approvers. Emits timesheet.approved / timesheet.rejected. Returns the week.


Permission	`timesheets.approve` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`timesheets_review` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`userId`	path	string	Yes	Up to 200 characters.

Request body

Field	Type	Required	Description
`weekStart`	string	Yes	The first day (Monday) of the week, YYYY-MM-DD.
`timeZone`	string	No	IANA timezone days and weeks are counted in (e.g. America/Chicago). Defaults to the organization's timezone (Settings → General). Up to 100 characters.
`decision`	enum	Yes	One of `APPROVED`, `REJECTED`.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/timesheets/{userId}/review" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"weekStart":"2026-11-03","decision":"APPROVED"}'

Response

200: the answer's fields

Field	Type	Description
`userId`	string
`userName`	string or null
`weekStart`	string
`timeZone`	string
`status`	enum or null	The week's state; null when empty. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`entries`	array of object
`entries[].id`	string
`entries[].organizationId`	string
`entries[].userId`	string
`entries[].technicianId`	string or null
`entries[].jobId`	string or null
`entries[].kind`	enum	SHIFT (clocked in), JOB (working a job), TRAVEL (on the way), BREAK, ACTIVITY (non-job work: see `activity`). One of `SHIFT`, `JOB`, `TRAVEL`, `BREAK`, `ACTIVITY`.
`entries[].activity`	enum or null	What an ACTIVITY entry was spent on. One of `SHOP`, `SUPPLY_HOUSE`, `MEETING`, `TRAINING`, `VEHICLE`, `ADMIN`, `OTHER`.
`entries[].startedAt`	string (date-time)
`entries[].endedAt`	string (date-time) or null
`entries[].note`	string or null
`entries[].source`	enum	One of `CLOCK`, `MANUAL`, `AUTO`.
`entries[].status`	enum	Approval state: OPEN, SUBMITTED, APPROVED or REJECTED. Running = `endedAt` null. One of `OPEN`, `SUBMITTED`, `APPROVED`, `REJECTED`.
`entries[].editReason`	string or null
`entries[].editedByUserId`	string or null
`entries[].approvedByUserId`	string or null
`entries[].approvedAt`	string (date-time) or null
`entries[].createdAt`	string (date-time)
`entries[].updatedAt`	string (date-time)
`entries[].job`	object or null
`entries[].job.id`	string
`entries[].job.identifier`	string
`entries[].technician`	object or null
`entries[].technician.id`	string
`entries[].technician.name`	string
`entries[].technician.color`	string
`entries[].userName`	string or null
`entries[].minutes`	integer	Whole minutes (a running entry counts to now).
`entries[].date`	string	The day it started, in the requested timezone.
`days`	array of object
`days[].SHIFT`	integer
`days[].JOB`	integer
`days[].TRAVEL`	integer
`days[].BREAK`	integer
`days[].ACTIVITY`	integer
`days[].paid`	integer	Paid minutes: SHIFT minus BREAK on a day with a shift, else JOB plus TRAVEL plus ACTIVITY.
`days[].date`	string
`totals`	object
`totals.SHIFT`	integer
`totals.JOB`	integer
`totals.TRAVEL`	integer
`totals.BREAK`	integer
`totals.ACTIVITY`	integer
`totals.paid`	integer	Paid minutes: SHIFT minus BREAK on a day with a shift, else JOB plus TRAVEL plus ACTIVITY.
`byJob`	array of object
`byJob[].jobId`	string
`byJob[].minutes`	integer
`byJob[].identifier`	string or null

Export a week as CSV

GET /organizations/{organizationId}/timesheets/export

The week's entries as CSV (person, date, kind, start, end, decimal hours, job, status, source, note), for payroll. Optionally one person (userId). Technicians: their own only. Read-only.

Permission: time.read (Owner, Admin, Dispatcher, Technician (own time)); risk read (OAuth scope servflo.read).


Permission	`time.read`
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`timesheets_export` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`weekStart`	query	string	Yes	The first day (Monday) of the week, YYYY-MM-DD.
`timeZone`	query	string	No	IANA timezone days and weeks are counted in (e.g. America/Chicago). Defaults to the organization's timezone (Settings → General). Up to 100 characters.
`userId`	query	string	No	Up to 200 characters.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/timesheets/export?weekStart=2026-11-03" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`fileName`	string
`contentType`	string
`csv`	string

On this page