Requests API

REST endpoints for requests in ServFlo: 11 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 requests	`GET /organizations/{organizationId}/requests`	`read`
Create a request	`POST /organizations/{organizationId}/requests`	`write`
Get a request with its customer, quotes and jobs	`GET /organizations/{organizationId}/requests/{requestId}`	`read`
Update a request	`PATCH /organizations/{organizationId}/requests/{requestId}`	`write`
Delete a request	`DELETE /organizations/{organizationId}/requests/{requestId}`	`sensitive`
Make the request's contact a customer	`POST /organizations/{organizationId}/requests/{requestId}/customer`	`write`
Convert a request to a draft quote	`POST /organizations/{organizationId}/requests/{requestId}/quote`	`write`
Schedule an on-site assessment	`POST /organizations/{organizationId}/requests/{requestId}/assessment`	`write`
Confirm an online booking	`POST /organizations/{organizationId}/requests/{requestId}/confirm-booking`	`write`
Online booking and portal settings	`GET /organizations/{organizationId}/booking-settings`	`read`
Turn online booking, portal job photos or customer sign-in on or off	`PATCH /organizations/{organizationId}/booking-settings`	`sensitive`

List requests

GET /organizations/{organizationId}/requests

Service requests (REQ-n) newest first: from the online booking form, the customer portal or entered by staff. Filter by text, status, source or customer; paged with a total. Read-only.


Permission	`requests.read` (Owner, Admin, Dispatcher, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`requests_list` (toolset `sales`, in the default set)

Parameters

Name	In	Type	Required	Description
`query`	query	string	No	Free-text search over the list's names, numbers and contact details. Up to 200 characters.
`status`	query	enum	No	One of `NEW`, `ASSESSMENT_SCHEDULED`, `QUOTED`, `CONVERTED`, `ARCHIVED`.
`source`	query	enum	No	One of `MANUAL`, `ONLINE_BOOKING`, `PORTAL`, `FIELD`, `PHONE`.
`customerId`	query	string	No
`businessUnitId`	query	string	No	Only this business unit (GET /business-units), or "none" for records without one. Up to 100 characters.
`limit`	query	integer	No	Page size, 1–200. Default `50`.
`offset`	query	integer	No	Rows to skip; the answer's `total` counts every match. Default `0`.

Example

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

Response

200: the answer's fields

Field	Type	Description
`items`	array of object
`items[].id`	string	Request id.
`items[].organizationId`	string
`items[].identifier`	string	REQ-n, unique per organization.
`items[].customerId`	string or null	Null while the request is from a new contact.
`items[].contactName`	string or null
`items[].contactCompany`	string or null
`items[].contactPhone`	string or null
`items[].contactEmail`	string or null
`items[].propertyId`	string or null
`items[].address`	string or null
`items[].serviceTypeId`	string or null
`items[].description`	string	What the customer asked for.
`items[].preferredDate`	string or null	YYYY-MM-DD
`items[].alternateDate`	string or null	YYYY-MM-DD
`items[].preferredTimeWindow`	enum	One of `ANY`, `MORNING`, `AFTERNOON`, `EVENING`.
`items[].bookedDate`	string or null	Online booking's slot day, YYYY-MM-DD.
`items[].bookedTime`	string or null	Hh: MM
`items[].bookedDurationMinutes`	integer or null
`items[].bookedTechnicianId`	string or null
`items[].source`	enum	Where it came from: MANUAL (staff), ONLINE_BOOKING, PORTAL, FIELD (a technician's lead) or PHONE (taken by the AI receptionist on a call). One of `MANUAL`, `ONLINE_BOOKING`, `PORTAL`, `FIELD`, `PHONE`.
`items[].leadTechnicianId`	string or null	The technician who sent a FIELD lead.
`items[].sourceJobId`	string or null	The job a FIELD lead came from.
`items[].leadUrgency`	enum or null	One of `NOW`, `SOON`, `LATER`.
`items[].status`	enum	NEW → ASSESSMENT_SCHEDULED / QUOTED → CONVERTED (a job was booked), or ARCHIVED. One of `NEW`, `ASSESSMENT_SCHEDULED`, `QUOTED`, `CONVERTED`, `ARCHIVED`.
`items[].internalNotes`	string or null
`items[].jobId`	string or null	The job booked from it.
`items[].assessmentJobId`	string or null	The on-site assessment job.
`items[].convertedAt`	string (date-time) or null
`items[].archivedAt`	string (date-time) or null
`items[].businessUnitId`	string or null
`items[].adCampaignId`	string or null	The ad campaign that brought it; null when not from an ad.
`items[].createdAt`	string (date-time)
`items[].updatedAt`	string (date-time)
`items[].customer`	object or null
`items[].customer.id`	string
`items[].customer.name`	string
`items[].property`	object or null
`items[].property.id`	string	Property id.
`items[].property.name`	string or null
`items[].property.address`	string or null
`items[].property.city`	string or null
`items[].serviceType`	object or null
`items[].serviceType.id`	string
`items[].serviceType.name`	string
`items[].serviceType.color`	string
`items[].businessUnit`	object or null	The business unit.
`items[].businessUnit.id`	string
`items[].businessUnit.name`	string
`items[].bookedTechnician`	object or null
`items[].bookedTechnician.id`	string	Technician id (GET /technicians).
`items[].bookedTechnician.name`	string
`items[].bookedTechnician.color`	string	Calendar colour, #rrggbb.
`items[].leadTechnician`	object or null
`items[].leadTechnician.id`	string	Technician id (GET /technicians).
`items[].leadTechnician.name`	string
`items[].leadTechnician.color`	string	Calendar colour, #rrggbb.
`items[].sourceJob`	object or null
`items[].sourceJob.id`	string
`items[].sourceJob.identifier`	string
`total`	integer	How many match the filters, across all pages.

Create a request

POST /organizations/{organizationId}/requests

Records a NEW service request (REQ-n). Name an existing customerId (search GET /customers first), or give contactName (and phone/email) for a new contact; no customer is created until POST /requests/{requestId}/customer. Nothing is sent to anyone.


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

Request body

Field	Type	Required	Description
`customerId`	string or null	No
`contactName`	string or null	No	Up to 200 characters.
`contactCompany`	string or null	No	Up to 200 characters.
`contactPhone`	string or null	No	Up to 50 characters.
`contactEmail`	empty string or string (email) or null	No
`propertyId`	string or null	No
`address`	string or null	No	Up to 500 characters.
`serviceTypeId`	string or null	No
`description`	string	Yes
`preferredDate`	empty string or string or null	No
`alternateDate`	empty string or string or null	No
`preferredTimeWindow`	enum	No	One of `ANY`, `MORNING`, `AFTERNOON`, `EVENING`.
`source`	enum	No	One of `MANUAL`, `ONLINE_BOOKING`, `PORTAL`, `FIELD`, `PHONE`.
`internalNotes`	string or null	No
`businessUnitId`	string or null	No	Business unit (GET /business-units); null = none. Omitted on create: the default (service type, then technician). Up to 100 characters.

Example

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

Response

201: the answer's fields

Field	Type	Description
`id`	string	Request id.
`organizationId`	string
`identifier`	string	REQ-n, unique per organization.
`customerId`	string or null	Null while the request is from a new contact.
`contactName`	string or null
`contactCompany`	string or null
`contactPhone`	string or null
`contactEmail`	string or null
`propertyId`	string or null
`address`	string or null
`serviceTypeId`	string or null
`description`	string	What the customer asked for.
`preferredDate`	string or null	YYYY-MM-DD
`alternateDate`	string or null	YYYY-MM-DD
`preferredTimeWindow`	enum	One of `ANY`, `MORNING`, `AFTERNOON`, `EVENING`.
`bookedDate`	string or null	Online booking's slot day, YYYY-MM-DD.
`bookedTime`	string or null	Hh: MM
`bookedDurationMinutes`	integer or null
`bookedTechnicianId`	string or null
`source`	enum	Where it came from: MANUAL (staff), ONLINE_BOOKING, PORTAL, FIELD (a technician's lead) or PHONE (taken by the AI receptionist on a call). One of `MANUAL`, `ONLINE_BOOKING`, `PORTAL`, `FIELD`, `PHONE`.
`leadTechnicianId`	string or null	The technician who sent a FIELD lead.
`sourceJobId`	string or null	The job a FIELD lead came from.
`leadUrgency`	enum or null	One of `NOW`, `SOON`, `LATER`.
`status`	enum	NEW → ASSESSMENT_SCHEDULED / QUOTED → CONVERTED (a job was booked), or ARCHIVED. One of `NEW`, `ASSESSMENT_SCHEDULED`, `QUOTED`, `CONVERTED`, `ARCHIVED`.
`internalNotes`	string or null
`jobId`	string or null	The job booked from it.
`assessmentJobId`	string or null	The on-site assessment job.
`convertedAt`	string (date-time) or null
`archivedAt`	string (date-time) or null
`businessUnitId`	string or null
`adCampaignId`	string or null	The ad campaign that brought it; null when not from an ad.
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`customer`	object or null
`customer.id`	string
`customer.name`	string
`property`	object or null
`property.id`	string	Property id.
`property.name`	string or null
`property.address`	string or null
`property.city`	string or null
`serviceType`	object or null
`serviceType.id`	string
`serviceType.name`	string
`serviceType.color`	string
`businessUnit`	object or null	The business unit.
`businessUnit.id`	string
`businessUnit.name`	string
`bookedTechnician`	object or null
`bookedTechnician.id`	string	Technician id (GET /technicians).
`bookedTechnician.name`	string
`bookedTechnician.color`	string	Calendar colour, #rrggbb.
`leadTechnician`	object or null
`leadTechnician.id`	string	Technician id (GET /technicians).
`leadTechnician.name`	string
`leadTechnician.color`	string	Calendar colour, #rrggbb.
`sourceJob`	object or null
`sourceJob.id`	string
`sourceJob.identifier`	string

Get a request with its customer, quotes and jobs

GET /organizations/{organizationId}/requests/{requestId}

One request with its customer, property, quotes and jobs. matchingCustomers lists existing customers with the contact's email or phone, when no customer is linked: link one with PATCH (customerId) rather than creating a duplicate. Read-only.


Permission	`requests.read` (Owner, Admin, Dispatcher, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`requests_get` (toolset `sales`, in the default set)

Parameters

Name	In	Type	Required	Description
`requestId`	path	string	Yes

Example

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

Response

200: the answer's fields

Field	Type	Description
`id`	string	Request id.
`organizationId`	string
`identifier`	string	REQ-n, unique per organization.
`customerId`	string or null	Null while the request is from a new contact.
`contactName`	string or null
`contactCompany`	string or null
`contactPhone`	string or null
`contactEmail`	string or null
`propertyId`	string or null
`address`	string or null
`serviceTypeId`	string or null
`description`	string	What the customer asked for.
`preferredDate`	string or null	YYYY-MM-DD
`alternateDate`	string or null	YYYY-MM-DD
`preferredTimeWindow`	enum	One of `ANY`, `MORNING`, `AFTERNOON`, `EVENING`.
`bookedDate`	string or null	Online booking's slot day, YYYY-MM-DD.
`bookedTime`	string or null	Hh: MM
`bookedDurationMinutes`	integer or null
`bookedTechnicianId`	string or null
`source`	enum	Where it came from: MANUAL (staff), ONLINE_BOOKING, PORTAL, FIELD (a technician's lead) or PHONE (taken by the AI receptionist on a call). One of `MANUAL`, `ONLINE_BOOKING`, `PORTAL`, `FIELD`, `PHONE`.
`leadTechnicianId`	string or null	The technician who sent a FIELD lead.
`sourceJobId`	string or null	The job a FIELD lead came from.
`leadUrgency`	enum or null	One of `NOW`, `SOON`, `LATER`.
`status`	enum	NEW → ASSESSMENT_SCHEDULED / QUOTED → CONVERTED (a job was booked), or ARCHIVED. One of `NEW`, `ASSESSMENT_SCHEDULED`, `QUOTED`, `CONVERTED`, `ARCHIVED`.
`internalNotes`	string or null
`jobId`	string or null	The job booked from it.
`assessmentJobId`	string or null	The on-site assessment job.
`convertedAt`	string (date-time) or null
`archivedAt`	string (date-time) or null
`businessUnitId`	string or null
`adCampaignId`	string or null	The ad campaign that brought it; null when not from an ad.
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`customer`	object or null
`customer.id`	string
`customer.name`	string
`customer.email`	string or null
`customer.phone`	string or null
`customer.status`	enum	LEAD until the first job, then ACTIVE; ARCHIVED customers leave the lists. One of `LEAD`, `ACTIVE`, `INACTIVE`, `ARCHIVED`.
`property`	object or null
`property.id`	string	Property id.
`property.name`	string or null
`property.address`	string or null
`property.city`	string or null
`property.state`	string or null
`property.zip`	string or null
`serviceType`	object or null
`serviceType.id`	string
`serviceType.name`	string
`serviceType.color`	string
`businessUnit`	object or null	The business unit.
`businessUnit.id`	string
`businessUnit.name`	string
`bookedTechnician`	object or null
`bookedTechnician.id`	string	Technician id (GET /technicians).
`bookedTechnician.name`	string
`bookedTechnician.color`	string	Calendar colour, #rrggbb.
`leadTechnician`	object or null
`leadTechnician.id`	string	Technician id (GET /technicians).
`leadTechnician.name`	string
`leadTechnician.color`	string	Calendar colour, #rrggbb.
`sourceJob`	object or null
`sourceJob.id`	string
`sourceJob.identifier`	string
`job`	object or null
`job.id`	string
`job.identifier`	string	JOB-n
`job.status`	enum	SCHEDULED, CONFIRMED, IN_PROGRESS, COMPLETED or CANCELLED. A job's status is its next open visit's. One of `SCHEDULED`, `CONFIRMED`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED`.
`job.scheduledDate`	string
`assessmentJob`	object or null
`assessmentJob.id`	string
`assessmentJob.identifier`	string	JOB-n
`assessmentJob.status`	enum	SCHEDULED, CONFIRMED, IN_PROGRESS, COMPLETED or CANCELLED. A job's status is its next open visit's. One of `SCHEDULED`, `CONFIRMED`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED`.
`assessmentJob.scheduledDate`	string
`quotes`	array of object
`quotes[].id`	string
`quotes[].identifier`	string	Q-n
`quotes[].status`	enum	DRAFT → SENT (customer can answer at /q/{publicToken}) → APPROVED / CHANGES_REQUESTED / DECLINED; APPROVED → CONVERTED (job or invoice made). SENT past `validUntil` becomes EXPIRED. One of `DRAFT`, `SENT`, `APPROVED`, `CHANGES_REQUESTED`, `DECLINED`, `CONVERTED`, `EXPIRED`, `ARCHIVED`.
`quotes[].title`	string
`matchingCustomers`	array of object	Existing customers with the contact's email or phone (up to 3) while the request has no customer.
`matchingCustomers[].id`	string
`matchingCustomers[].name`	string
`matchingCustomers[].email`	string or null
`matchingCustomers[].phone`	string or null

Update a request

PATCH /organizations/{organizationId}/requests/{requestId}

Changes the fields sent. status: ARCHIVED archives it; NEW reopens an archived request. To quote or book it use POST /requests/{requestId}/quote, /assessment or POST /jobs with requestId.


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

Parameters

Name	In	Type	Required	Description
`requestId`	path	string	Yes

Request body

Field	Type	Required	Description
`customerId`	string or null	No
`contactName`	string or null	No	Up to 200 characters.
`contactCompany`	string or null	No	Up to 200 characters.
`contactPhone`	string or null	No	Up to 50 characters.
`contactEmail`	empty string or string (email) or null	No
`propertyId`	string or null	No
`address`	string or null	No	Up to 500 characters.
`serviceTypeId`	string or null	No
`description`	string	No
`preferredDate`	empty string or string or null	No
`alternateDate`	empty string or string or null	No
`preferredTimeWindow`	enum	No	One of `ANY`, `MORNING`, `AFTERNOON`, `EVENING`.
`source`	enum	No	One of `MANUAL`, `ONLINE_BOOKING`, `PORTAL`, `FIELD`, `PHONE`.
`internalNotes`	string or null	No
`businessUnitId`	string or null	No	Business unit (GET /business-units); null = none. Omitted on create: the default (service type, then technician). Up to 100 characters.
`status`	enum	No	One of `NEW`, `ASSESSMENT_SCHEDULED`, `QUOTED`, `CONVERTED`, `ARCHIVED`.

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/requests/{requestId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"customer_id","contactName":"string","contactCompany":"string"}'

Response

200: the answer's fields

Field	Type	Description
`id`	string	Request id.
`organizationId`	string
`identifier`	string	REQ-n, unique per organization.
`customerId`	string or null	Null while the request is from a new contact.
`contactName`	string or null
`contactCompany`	string or null
`contactPhone`	string or null
`contactEmail`	string or null
`propertyId`	string or null
`address`	string or null
`serviceTypeId`	string or null
`description`	string	What the customer asked for.
`preferredDate`	string or null	YYYY-MM-DD
`alternateDate`	string or null	YYYY-MM-DD
`preferredTimeWindow`	enum	One of `ANY`, `MORNING`, `AFTERNOON`, `EVENING`.
`bookedDate`	string or null	Online booking's slot day, YYYY-MM-DD.
`bookedTime`	string or null	Hh: MM
`bookedDurationMinutes`	integer or null
`bookedTechnicianId`	string or null
`source`	enum	Where it came from: MANUAL (staff), ONLINE_BOOKING, PORTAL, FIELD (a technician's lead) or PHONE (taken by the AI receptionist on a call). One of `MANUAL`, `ONLINE_BOOKING`, `PORTAL`, `FIELD`, `PHONE`.
`leadTechnicianId`	string or null	The technician who sent a FIELD lead.
`sourceJobId`	string or null	The job a FIELD lead came from.
`leadUrgency`	enum or null	One of `NOW`, `SOON`, `LATER`.
`status`	enum	NEW → ASSESSMENT_SCHEDULED / QUOTED → CONVERTED (a job was booked), or ARCHIVED. One of `NEW`, `ASSESSMENT_SCHEDULED`, `QUOTED`, `CONVERTED`, `ARCHIVED`.
`internalNotes`	string or null
`jobId`	string or null	The job booked from it.
`assessmentJobId`	string or null	The on-site assessment job.
`convertedAt`	string (date-time) or null
`archivedAt`	string (date-time) or null
`businessUnitId`	string or null
`adCampaignId`	string or null	The ad campaign that brought it; null when not from an ad.
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`customer`	object or null
`customer.id`	string
`customer.name`	string
`property`	object or null
`property.id`	string	Property id.
`property.name`	string or null
`property.address`	string or null
`property.city`	string or null
`serviceType`	object or null
`serviceType.id`	string
`serviceType.name`	string
`serviceType.color`	string
`businessUnit`	object or null	The business unit.
`businessUnit.id`	string
`businessUnit.name`	string
`bookedTechnician`	object or null
`bookedTechnician.id`	string	Technician id (GET /technicians).
`bookedTechnician.name`	string
`bookedTechnician.color`	string	Calendar colour, #rrggbb.
`leadTechnician`	object or null
`leadTechnician.id`	string	Technician id (GET /technicians).
`leadTechnician.name`	string
`leadTechnician.color`	string	Calendar colour, #rrggbb.
`sourceJob`	object or null
`sourceJob.id`	string
`sourceJob.identifier`	string

Delete a request

DELETE /organizations/{organizationId}/requests/{requestId}

Destructive: deletes the request. Quotes and jobs made from it stay. Prefer archiving (PATCH status: ARCHIVED).


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

Parameters

Name	In	Type	Required	Description
`requestId`	path	string	Yes

Example

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

Response

200: the answer's fields

Field	Type	Description
`ok`	true

Make the request's contact a customer

POST /organizations/{organizationId}/requests/{requestId}/customer

Creates a LEAD customer (and a property from the address) from the request's contact when the request has none, and links it; returns the request. Check matchingCustomers on GET /requests/{requestId} first to avoid duplicates.


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

Parameters

Name	In	Type	Required	Description
`requestId`	path	string	Yes

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/requests/{requestId}/customer" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string	Request id.
`organizationId`	string
`identifier`	string	REQ-n, unique per organization.
`customerId`	string or null	Null while the request is from a new contact.
`contactName`	string or null
`contactCompany`	string or null
`contactPhone`	string or null
`contactEmail`	string or null
`propertyId`	string or null
`address`	string or null
`serviceTypeId`	string or null
`description`	string	What the customer asked for.
`preferredDate`	string or null	YYYY-MM-DD
`alternateDate`	string or null	YYYY-MM-DD
`preferredTimeWindow`	enum	One of `ANY`, `MORNING`, `AFTERNOON`, `EVENING`.
`bookedDate`	string or null	Online booking's slot day, YYYY-MM-DD.
`bookedTime`	string or null	Hh: MM
`bookedDurationMinutes`	integer or null
`bookedTechnicianId`	string or null
`source`	enum	Where it came from: MANUAL (staff), ONLINE_BOOKING, PORTAL, FIELD (a technician's lead) or PHONE (taken by the AI receptionist on a call). One of `MANUAL`, `ONLINE_BOOKING`, `PORTAL`, `FIELD`, `PHONE`.
`leadTechnicianId`	string or null	The technician who sent a FIELD lead.
`sourceJobId`	string or null	The job a FIELD lead came from.
`leadUrgency`	enum or null	One of `NOW`, `SOON`, `LATER`.
`status`	enum	NEW → ASSESSMENT_SCHEDULED / QUOTED → CONVERTED (a job was booked), or ARCHIVED. One of `NEW`, `ASSESSMENT_SCHEDULED`, `QUOTED`, `CONVERTED`, `ARCHIVED`.
`internalNotes`	string or null
`jobId`	string or null	The job booked from it.
`assessmentJobId`	string or null	The on-site assessment job.
`convertedAt`	string (date-time) or null
`archivedAt`	string (date-time) or null
`businessUnitId`	string or null
`adCampaignId`	string or null	The ad campaign that brought it; null when not from an ad.
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`customer`	object or null
`customer.id`	string
`customer.name`	string
`customer.email`	string or null
`customer.phone`	string or null
`customer.status`	enum	LEAD until the first job, then ACTIVE; ARCHIVED customers leave the lists. One of `LEAD`, `ACTIVE`, `INACTIVE`, `ARCHIVED`.
`property`	object or null
`property.id`	string	Property id.
`property.name`	string or null
`property.address`	string or null
`property.city`	string or null
`property.state`	string or null
`property.zip`	string or null
`serviceType`	object or null
`serviceType.id`	string
`serviceType.name`	string
`serviceType.color`	string
`businessUnit`	object or null	The business unit.
`businessUnit.id`	string
`businessUnit.name`	string
`bookedTechnician`	object or null
`bookedTechnician.id`	string	Technician id (GET /technicians).
`bookedTechnician.name`	string
`bookedTechnician.color`	string	Calendar colour, #rrggbb.
`leadTechnician`	object or null
`leadTechnician.id`	string	Technician id (GET /technicians).
`leadTechnician.name`	string
`leadTechnician.color`	string	Calendar colour, #rrggbb.
`sourceJob`	object or null
`sourceJob.id`	string
`sourceJob.identifier`	string
`job`	object or null
`job.id`	string
`job.identifier`	string	JOB-n
`job.status`	enum	SCHEDULED, CONFIRMED, IN_PROGRESS, COMPLETED or CANCELLED. A job's status is its next open visit's. One of `SCHEDULED`, `CONFIRMED`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED`.
`job.scheduledDate`	string
`assessmentJob`	object or null
`assessmentJob.id`	string
`assessmentJob.identifier`	string	JOB-n
`assessmentJob.status`	enum	SCHEDULED, CONFIRMED, IN_PROGRESS, COMPLETED or CANCELLED. A job's status is its next open visit's. One of `SCHEDULED`, `CONFIRMED`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED`.
`assessmentJob.scheduledDate`	string
`quotes`	array of object
`quotes[].id`	string
`quotes[].identifier`	string	Q-n
`quotes[].status`	enum	DRAFT → SENT (customer can answer at /q/{publicToken}) → APPROVED / CHANGES_REQUESTED / DECLINED; APPROVED → CONVERTED (job or invoice made). SENT past `validUntil` becomes EXPIRED. One of `DRAFT`, `SENT`, `APPROVED`, `CHANGES_REQUESTED`, `DECLINED`, `CONVERTED`, `EXPIRED`, `ARCHIVED`.
`quotes[].title`	string
`matchingCustomers`	array of object	Existing customers with the contact's email or phone (up to 3) while the request has no customer.
`matchingCustomers[].id`	string
`matchingCustomers[].name`	string
`matchingCustomers[].email`	string or null
`matchingCustomers[].phone`	string or null

Convert a request to a draft quote

POST /organizations/{organizationId}/requests/{requestId}/quote

Creates a DRAFT quote for the request (and the customer, if the request is from a new contact); the request becomes QUOTED. Fill the quote with PATCH /quotes/{quoteId}; nothing is sent.


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

Parameters

Name	In	Type	Required	Description
`requestId`	path	string	Yes

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/requests/{requestId}/quote" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

201: the answer's fields

Field	Type	Description
`id`	string	Quote id.
`organizationId`	string
`identifier`	string	Q-n, unique per organization.
`customerId`	string
`propertyId`	string or null
`requestId`	string or null	The request it was made from.
`title`	string
`message`	string or null	Shown to the customer.
`validUntil`	string or null	YYYY-MM-DD; a sent quote expires after it.
`status`	enum	DRAFT → SENT (customer can answer at /q/{publicToken}) → APPROVED / CHANGES_REQUESTED / DECLINED; APPROVED → CONVERTED (job or invoice made). SENT past `validUntil` becomes EXPIRED. One of `DRAFT`, `SENT`, `APPROVED`, `CHANGES_REQUESTED`, `DECLINED`, `CONVERTED`, `EXPIRED`, `ARCHIVED`.
`taxRate`	number	Tax rate in percent.
`depositPercent`	number or null	Deposit asked, as a percent of the total.
`depositCents`	integer or null	Deposit asked, as a fixed amount in cents.
`internalNotes`	string or null
`publicToken`	string	The customer link token: the quote page is /q/{publicToken}.
`sentAt`	string (date-time) or null
`approvedAt`	string (date-time) or null
`approvedOptionId`	string or null
`approvedLineIds`	array of string	The optional lines the customer kept.
`approvedTotalCents`	integer or null	Approved total in cents, with tax.
`approvedDepositCents`	integer or null	Approved deposit in cents.
`signatureName`	string or null
`approvedByStaff`	boolean	Staff recorded the approval for the customer.
`changesRequestedAt`	string (date-time) or null
`changesRequestedNote`	string or null
`declinedAt`	string (date-time) or null
`declineReason`	string or null
`jobId`	string or null	The job it was converted to.
`invoiceId`	string or null	The invoice it was converted to.
`convertedAt`	string (date-time) or null
`memberPricingRemoved`	boolean
`soldByUserId`	string or null
`soldByTechnicianId`	string or null
`financingDisabled`	boolean
`businessUnitId`	string or null
`customFields`	any	Custom field values by key (definitions: GET /custom-fields?entity=QUOTE).
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

Schedule an on-site assessment

POST /organizations/{organizationId}/requests/{requestId}/assessment

Books a job (JOB-n) noted as the request's on-site assessment, creating the customer if needed; the request becomes ASSESSMENT_SCHEDULED. Nothing is sent to the customer.


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

Parameters

Name	In	Type	Required	Description
`requestId`	path	string	Yes

Request body

Field	Type	Required	Description
`scheduledDate`	string	Yes	A calendar date in the business's own calendar, YYYY-MM-DD.
`scheduledTime`	string or null	No	A local time of day, HH:MM (24-hour). Blank means 09:00 on new jobs.
`technicianId`	string or null	No
`notes`	string or null	No

Example

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

Response

201: the answer's fields

Field	Type	Description
`id`	string	Job id.
`organizationId`	string
`identifier`	string	JOB-n, unique per organization.
`customerId`	string
`propertyId`	string or null
`assetId`	string or null	The equipment worked on.
`technicianId`	string or null	The lead technician of the next open visit.
`serviceTypeId`	string or null
`status`	enum	SCHEDULED, CONFIRMED, IN_PROGRESS, COMPLETED or CANCELLED. A job's status is its next open visit's. One of `SCHEDULED`, `CONFIRMED`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED`.
`priority`	enum	One of `LOW`, `NORMAL`, `HIGH`, `URGENT`.
`scheduledDate`	string	The next open visit's day, YYYY-MM-DD.
`scheduledTime`	string or null	Hh: MM
`durationMinutes`	integer
`priceCents`	integer	Job price before tax, in integer cents.
`address`	string or null
`notes`	string or null
`completionNotes`	string or null	What was done.
`recurrenceInterval`	enum or null	One of `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `QUARTERLY`, `YEARLY`.
`recurrenceParentId`	string or null
`onMyWayAt`	string (date-time) or null
`arrivedAt`	string (date-time) or null
`startedAt`	string (date-time) or null
`completedAt`	string (date-time) or null
`signedBy`	string or null	Who signed the work off on site.
`signedAt`	string (date-time) or null
`businessUnitId`	string or null
`customFields`	any	Custom field values by key (definitions: GET /custom-fields?entity=JOB).
`weatherSensitive`	boolean or null	Plans around the weather: overrides the service type; null follows it.
`createdAt`	string (date-time)
`updatedAt`	string (date-time)
`customer`	object
`customer.id`	string	Customer id.
`customer.name`	string
`customer.phone`	string or null
`technician`	object or null
`technician.id`	string	Technician id (GET /technicians).
`technician.name`	string
`technician.color`	string	Calendar colour, #rrggbb.
`serviceType`	object or null
`serviceType.id`	string
`serviceType.name`	string
`serviceType.color`	string
`businessUnit`	object or null	The business unit.
`businessUnit.id`	string
`businessUnit.name`	string
`asset`	object or null
`asset.id`	string
`asset.name`	string
`asset.serialNumber`	string
`property`	object or null
`property.id`	string	Property id.
`property.name`	string or null
`property.address`	string or null
`property.city`	string or null
`property.taxRate`	number or null
`nextJobId`	string or null	After an update: the next occurrence booked when a recurring job completed.

Confirm an online booking

POST /organizations/{organizationId}/requests/{requestId}/confirm-booking

Turns the time a customer booked online (bookedDate, bookedTime on the request) into a job (JOB-n) at that time, creating the customer from the contact when none is linked (link an existing one first with PATCH /requests/{requestId} customerId to avoid a duplicate). The technician defaults to the one the slot holds; pass technicianId (or null) to change it. The request becomes CONVERTED. Only NEW requests with a booked time. Nothing is sent by this call; automations may react to booking.confirmed.


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

Parameters

Name	In	Type	Required	Description
`requestId`	path	string	Yes

Request body

Field	Type	Required	Description
`technicianId`	string or null	No	Assign someone else (or null for nobody).

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/requests/{requestId}/confirm-booking" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"technicianId":"technician_id"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string
`identifier`	string	JOB-n
`scheduledDate`	string
`scheduledTime`	string or null
`technicianId`	string or null

Online booking and portal settings

GET /organizations/{organizationId}/booking-settings

Whether the public booking form (/book/{slug}) takes requests, whether the customer portal shows completed jobs' photos, and whether customers can sign in to their portal (/c/{slug}). Read-only.


Permission	`settings.read` (Owner, Admin, Dispatcher)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`bookingSettings_get` (toolset `settings`)

Example

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

Response

200: the answer's fields

Field	Type	Description
`slug`	string	The booking form is at /book/{slug}.
`bookingEnabled`	boolean
`portalShowJobPhotos`	boolean	Whether the customer portal shows the photos of completed jobs (default off).
`customerSignInEnabled`	boolean	Whether customers can sign in to their portal at /c/{slug} with a code sent to their email or phone (default on).

Turn online booking, portal job photos or customer sign-in on or off

PATCH /organizations/{organizationId}/booking-settings

customerSignInEnabled off REVOKES ACCESS: every customer is signed out of their portal at once and /c/{slug} stops offering sign-in (portal links keep working). bookingEnabled off: the public booking form and /api/public/book/{slug} answer 404 and take no requests; on: anyone with the link can send a request. portalShowJobPhotos on EXPOSES the before/after/general photos of completed jobs to customers in their portal (never ISSUE photos or signatures). Send either or both. Needs settings.manage (owners and admins).


Permission	`settings.manage` (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	`bookingSettings_update` (toolset `settings`)
Approval	Over MCP, this tool asks for your OK first (in the AI app when it supports it, otherwise in ServFlo). See Approvals.

Request body

Field	Type	Required	Description
`bookingEnabled`	boolean	No
`portalShowJobPhotos`	boolean	No	Show completed jobs' photos to customers in their portal.
`customerSignInEnabled`	boolean	No	Let customers sign in to their portal with a code (on by default). Off signs every customer out at once.

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/booking-settings" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bookingEnabled":true,"portalShowJobPhotos":true,"customerSignInEnabled":true}'

Response

200: the answer's fields

Field	Type	Description
`slug`	string	The booking form is at /book/{slug}.
`bookingEnabled`	boolean
`portalShowJobPhotos`	boolean	Whether the customer portal shows the photos of completed jobs (default off).
`customerSignInEnabled`	boolean	Whether customers can sign in to their portal at /c/{slug} with a code sent to their email or phone (default on).

On this page