Technicians API

REST endpoints for technicians in ServFlo: 10 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
List technicians with open job counts	`GET /organizations/{organizationId}/technicians`	`read`
Create a technician	`POST /organizations/{organizationId}/technicians`	`write`
Active technicians, for pickers	`GET /organizations/{organizationId}/technicians/options`	`read`
Update a technician	`PATCH /organizations/{organizationId}/technicians/{technicianId}`	`write`
Delete a technician	`DELETE /organizations/{organizationId}/technicians/{technicianId}`	`sensitive`
Link a member's account to a technician	`POST /organizations/{organizationId}/technicians/{technicianId}/link`	`sensitive`
Unlink a technician's account	`DELETE /organizations/{organizationId}/technicians/{technicianId}/link`	`sensitive`
List technicians' time off	`GET /organizations/{organizationId}/time-off`	`read`
Add time off	`POST /organizations/{organizationId}/time-off`	`write`
Delete time off	`DELETE /organizations/{organizationId}/time-off/{timeOffId}`	`sensitive`

List technicians with open job counts

GET /organizations/{organizationId}/technicians

Every technician (active and inactive) with contact details, calendar colour and openJobCount. Read-only. Use GET /technicians/options for pickers.


Permission	`technicians.read` (Owner, Admin, Dispatcher, Technician, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`technicians_list` (toolset `team`)

Example

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

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string	Technician id.
`organizationId`	string
`name`	string
`email`	string or null
`phone`	string or null
`color`	string	Calendar colour, #rrggbb.
`active`	boolean
`userId`	string or null	The linked ServFlo account, if any.
`invitedEmail`	string or null
`invitedAt`	string (date-time) or null
`workStartTime`	string	Working day start, HH:MM (24-hour).
`workEndTime`	string	Working day end, HH:MM (24-hour).
`homeAddress`	string or null
`homeLatitude`	number or null
`homeLongitude`	number or null
`workDays`	array of integer	Working weekdays, 0 = Sunday … 6 = Saturday.
`onlineBookable`	boolean
`hourlyCostCents`	integer or null	Loaded hourly cost in cents (costing.read only).
`hourlyPayCents`	integer or null	Hourly pay in cents (costing.read only).
`homeBusinessUnitId`	string or null
`customFields`	any	Custom field values by key (definitions: GET /custom-fields?entity=TECHNICIAN).
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`businessUnitIds`	array of string
`openJobCount`	integer	Jobs still open on their plate.

Create a technician

POST /organizations/{organizationId}/technicians

Adds a technician (a person jobs are assigned to; not a sign-in account). Returns the technician.


Permission	`technicians.write` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`technicians_create` (toolset `team`, in the default set)

Request body

Field	Type	Required	Description
`name`	string	Yes
`customFields`	object	No	Technician custom field values (GET /custom-fields?entity=TECHNICIAN), e.g. licence number or van; required ones are checked on create.
`email`	empty string or string (email) or null	No
`phone`	string or null	No
`color`	string	No
`active`	boolean	No
`workStartTime`	string	No	Start of their working day, HH:MM (default 08:00); the dispatch board warns outside it.
`workEndTime`	string	No	End of their working day, HH:MM (default 17:00).
`homeAddress`	string or null	No	Where their day starts when not at the business (route planning); geocoded after saving. Up to 500 characters.
`homeLatitude`	number or null	No	Home base pinned by hand (WGS84). -90–90.
`homeLongitude`	number or null	No	-180–180.
`hourlyCostCents`	integer or null	No	Burdened cost of one hour of their time, cents (job costing). Hidden from roles without `costing.read`. 0–10000000.
`hourlyPayCents`	integer or null	No	Their hourly pay, cents. Hidden from roles without `costing.read`. 0–10000000.
`workDays`	array of integer	No	Days they work, 0 = Sunday … 6 = Saturday (default Monday–Friday): online booking offers only these. Up to 7 items.
`onlineBookable`	boolean	No	Whether online booking may offer and assign their time (default true).
`homeBusinessUnitId`	string or null	No	Their home business unit (GET /business-units): new jobs they are assigned default to it when the service type names none. Up to 100 characters.
`businessUnitIds`	array of string	No	Other units they may work for (replaces the list). With no units at all they work for every unit. Up to 100 items.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/technicians" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dana Whitfield"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string	Technician id.
`organizationId`	string
`name`	string
`email`	string or null
`phone`	string or null
`color`	string	Calendar colour, #rrggbb.
`active`	boolean
`userId`	string or null	The linked ServFlo account, if any.
`invitedEmail`	string or null
`invitedAt`	string (date-time) or null
`workStartTime`	string	Working day start, HH:MM (24-hour).
`workEndTime`	string	Working day end, HH:MM (24-hour).
`homeAddress`	string or null
`homeLatitude`	number or null
`homeLongitude`	number or null
`workDays`	array of integer	Working weekdays, 0 = Sunday … 6 = Saturday.
`onlineBookable`	boolean
`hourlyCostCents`	integer or null	Loaded hourly cost in cents (costing.read only).
`hourlyPayCents`	integer or null	Hourly pay in cents (costing.read only).
`homeBusinessUnitId`	string or null
`customFields`	any	Custom field values by key (definitions: GET /custom-fields?entity=TECHNICIAN).
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

Active technicians, for pickers

GET /organizations/{organizationId}/technicians/options

Active technicians as id, name and colour, for assigning jobs (POST /jobs/{jobId}/assign). Read-only.


Permission	`technicians.read` (Owner, Admin, Dispatcher, Technician, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`technicians_options` (toolset `team`, in the default set)

Example

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

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string	Technician id.
`name`	string
`color`	string
`workStartTime`	string
`workEndTime`	string
`homeBusinessUnitId`	string or null
`businessUnitIds`	array of string

Update a technician

PATCH /organizations/{organizationId}/technicians/{technicianId}

Changes the fields sent; active: false hides them from pickers while keeping their jobs. Returns the technician.


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

Parameters

Name	In	Type	Required	Description
`technicianId`	path	string	Yes

Request body

Field	Type	Required	Description
`name`	string	No
`customFields`	object	No	Technician custom field values (GET /custom-fields?entity=TECHNICIAN), e.g. licence number or van; required ones are checked on create.
`email`	empty string or string (email) or null	No
`phone`	string or null	No
`color`	string	No
`active`	boolean	No
`workStartTime`	string	No	Start of their working day, HH:MM (default 08:00); the dispatch board warns outside it.
`workEndTime`	string	No	End of their working day, HH:MM (default 17:00).
`homeAddress`	string or null	No	Where their day starts when not at the business (route planning); geocoded after saving. Up to 500 characters.
`homeLatitude`	number or null	No	Home base pinned by hand (WGS84). -90–90.
`homeLongitude`	number or null	No	-180–180.
`hourlyCostCents`	integer or null	No	Burdened cost of one hour of their time, cents (job costing). Hidden from roles without `costing.read`. 0–10000000.
`hourlyPayCents`	integer or null	No	Their hourly pay, cents. Hidden from roles without `costing.read`. 0–10000000.
`workDays`	array of integer	No	Days they work, 0 = Sunday … 6 = Saturday (default Monday–Friday): online booking offers only these. Up to 7 items.
`onlineBookable`	boolean	No	Whether online booking may offer and assign their time (default true).
`homeBusinessUnitId`	string or null	No	Their home business unit (GET /business-units): new jobs they are assigned default to it when the service type names none. Up to 100 characters.
`businessUnitIds`	array of string	No	Other units they may work for (replaces the list). With no units at all they work for every unit. Up to 100 items.

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/technicians/{technicianId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dana Whitfield","customFields":{},"email":"dana@example.com"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string	Technician id.
`organizationId`	string
`name`	string
`email`	string or null
`phone`	string or null
`color`	string	Calendar colour, #rrggbb.
`active`	boolean
`userId`	string or null	The linked ServFlo account, if any.
`invitedEmail`	string or null
`invitedAt`	string (date-time) or null
`workStartTime`	string	Working day start, HH:MM (24-hour).
`workEndTime`	string	Working day end, HH:MM (24-hour).
`homeAddress`	string or null
`homeLatitude`	number or null
`homeLongitude`	number or null
`workDays`	array of integer	Working weekdays, 0 = Sunday … 6 = Saturday.
`onlineBookable`	boolean
`hourlyCostCents`	integer or null	Loaded hourly cost in cents (costing.read only).
`hourlyPayCents`	integer or null	Hourly pay in cents (costing.read only).
`homeBusinessUnitId`	string or null
`customFields`	any	Custom field values by key (definitions: GET /custom-fields?entity=TECHNICIAN).
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

Delete a technician

DELETE /organizations/{organizationId}/technicians/{technicianId}

Destructive: deletes the technician; their jobs stay, unassigned. Prefer active: false (PATCH) to keep history.


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

Parameters

Name	In	Type	Required	Description
`technicianId`	path	string	Yes

Example

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

Response

200: the answer's fields

Field	Type	Description
`ok`	true

Link a member's account to a technician

POST /organizations/{organizationId}/technicians/{technicianId}/link

Grants access: links an organization member (GET /members) to this technician record: they then see this technician's jobs, customers and My day, and their time is recorded against it. A member can be linked to one technician only (409). Returns the technician.


Permission	`technicians.write` (Owner, Admin)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`technicians_link` (toolset `team`)
Approval	Over MCP, this tool asks for your OK first (in the AI app when it supports it, otherwise in ServFlo). See Approvals.

Parameters

Name	In	Type	Required	Description
`technicianId`	path	string	Yes

Request body

Field	Type	Required	Description
`userId`	string	Yes	The member's user id (GET /members). Up to 200 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/technicians/{technicianId}/link" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user_id"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string
`name`	string
`email`	string or null
`phone`	string or null
`color`	string
`active`	boolean
`userId`	string or null	The linked ServFlo account, if any.
`invitedEmail`	string or null
`invitedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

Unlink a technician's account

DELETE /organizations/{organizationId}/technicians/{technicianId}/link

Revokes access: the account is no longer this technician (it stays a member; change or remove its role in Members). Clears a pending invitation too. Their jobs and time stay.


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

Parameters

Name	In	Type	Required	Description
`technicianId`	path	string	Yes

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/technicians/{technicianId}/link" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`name`	string
`email`	string or null
`phone`	string or null
`color`	string
`active`	boolean
`userId`	string or null	The linked ServFlo account, if any.
`invitedEmail`	string or null
`invitedAt`	string (date-time) or null
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

List technicians' time off

GET /organizations/{organizationId}/time-off

Time off that ends on or after from (default today), soonest first, optionally for one technician. Online booking offers no slots in it. Read-only.


Permission	`technicians.read` (Owner, Admin, Dispatcher, Technician, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`timeOff_list` (toolset `scheduling`)

Parameters

Name	In	Type	Required	Description
`technicianId`	query	string	No
`from`	query	empty string or string	No	Only time off ending on or after this day.

Example

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

Response

200: the answer's fields

Field	Type	Description
`items`	array of object
`items[].id`	string
`items[].technicianId`	string
`items[].startDate`	string
`items[].endDate`	string
`items[].startTime`	string or null
`items[].endTime`	string or null
`items[].reason`	string or null
`items[].createdAt`	string (date-time)
`items[].technician`	object
`items[].technician.id`	string
`items[].technician.name`	string
`items[].technician.color`	string

Add time off

POST /organizations/{organizationId}/time-off

Marks a technician away from startDate to endDate (inclusive): whole days, or startTime–endTime on each of those days. Online booking stops offering that time; existing jobs are not moved (check the dispatch board).


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

Request body

Field	Type	Required	Description
`technicianId`	string	Yes
`startDate`	string	Yes	A calendar date in the business's own calendar, YYYY-MM-DD.
`endDate`	string	Yes	A calendar date in the business's own calendar, YYYY-MM-DD.
`startTime`	string or null	No	With `endTime`: part of each day; omit for whole days.
`endTime`	string or null	No	A local time of day, HH:MM (24-hour). Blank means 09:00 on new jobs.
`reason`	string or null	No	Up to 200 characters.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/time-off" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"technicianId":"technician_id","startDate":"2026-11-03","endDate":"2026-11-03"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string
`technicianId`	string
`startDate`	string
`endDate`	string
`startTime`	string or null
`endTime`	string or null
`reason`	string or null
`createdAt`	string (date-time)
`technician`	object
`technician.id`	string
`technician.name`	string
`technician.color`	string

Delete time off

DELETE /organizations/{organizationId}/time-off/{timeOffId}

Destructive: removes the time off; online booking may offer that time again at once.


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

Parameters

Name	In	Type	Required	Description
`timeOffId`	path	string	Yes

Example

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

Response

200: the answer's fields

Field	Type	Description
`ok`	true

On this page