Reviews API

REST endpoints for reviews 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
Reviews overview	`GET /organizations/{organizationId}/reviews`	`read`
List reviews	`GET /organizations/{organizationId}/reviews/items`	`read`
A review	`GET /organizations/{organizationId}/reviews/items/{reviewId}`	`read`
Sync reviews now	`POST /organizations/{organizationId}/reviews/sync`	`write`
Follow a location's reviews	`PATCH /organizations/{organizationId}/reviews/locations/{reviewLocationId}`	`write`
Draft a reply	`POST /organizations/{organizationId}/reviews/items/{reviewId}/draft-reply`	`write`
Reply to a review	`POST /organizations/{organizationId}/reviews/items/{reviewId}/reply`	`sensitive`
Remove a reply	`DELETE /organizations/{organizationId}/reviews/items/{reviewId}/reply`	`sensitive`
Start connecting Google	`POST /organizations/{organizationId}/reviews/google/connect`	`sensitive`
Disconnect Google	`POST /organizations/{organizationId}/reviews/google/disconnect`	`sensitive`
Customer feedback	`GET /organizations/{organizationId}/feedback`	`read`

Reviews overview

GET /organizations/{organizationId}/reviews

Whether Google is connected, the Business Profile locations (and which are followed), and the rating summary: count, average, 1–5 star distribution, unanswered and last 30 days. Read-only.


Permission	`reviews.read` (Owner, Admin, Dispatcher, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`reviews_overview` (toolset `marketing`)

Example

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

Response

200: the answer's fields

Field	Type	Description
`google`	object
`google.mode`	enum	unconfigured: this server has no Google OAuth client. One of `live`, `fake`, `unconfigured`.
`google.connected`	boolean
`google.status`	string
`google.account`	string or null	The Google account the Business Profile is managed with.
`google.connectedAt`	string (date-time) or null
`google.lastSyncAt`	string (date-time) or null
`google.lastError`	string or null
`locations`	array of object
`locations[].id`	string
`locations[].title`	string
`locations[].address`	string
`locations[].reviewUrl`	string or null	Where customers write a review of this location.
`locations[].selected`	boolean	Reviews are followed for selected locations.
`locations[].lastSyncedAt`	string (date-time) or null
`locations[].lastError`	string or null
`summary`	object
`summary.count`	integer
`summary.average`	number or null
`summary.distribution`	array of integer	Counts of 1, 2, 3, 4 and 5-star reviews.
`summary.unanswered`	integer
`summary.last30Days`	integer

List reviews

GET /organizations/{organizationId}/reviews/items

Google reviews of the followed locations, newest first, filtered by rating, unanswered (no reply yet) or location; paged by limit/offset with a total. Each carries the matched customer when a reviewer's name matched one. Read-only.


Permission	`reviews.read` (Owner, Admin, Dispatcher, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`reviews_list` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`rating`	query	integer	No	1–5.
`unanswered`	query	boolean	No
`reviewLocationId`	query	string	No
`limit`	query	integer	No	1–100.
`offset`	query	integer	No	0–100000.

Example

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

Response

200: the answer's fields

Field	Type	Description
`items`	array of object
`items[].id`	string
`items[].reviewerName`	string
`items[].reviewerPhotoUrl`	string or null
`items[].rating`	integer	1–5 stars (0 when Google gave none).
`items[].comment`	string
`items[].postedAt`	string (date-time)
`items[].editedAt`	string (date-time)
`items[].reply`	string or null	The business's public reply, when there is one.
`items[].repliedAt`	string (date-time) or null
`items[].customerId`	string or null
`items[].customer`	object or null
`items[].customer.id`	string
`items[].customer.name`	string
`items[].location`	object
`items[].location.id`	string
`items[].location.title`	string
`total`	integer

A review

GET /organizations/{organizationId}/reviews/items/{reviewId}

One Google review with the business's reply and the matched customer. Read-only.


Permission	`reviews.read` (Owner, Admin, Dispatcher, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`reviews_get` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`reviewId`	path	string	Yes

Example

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

Response

200: the answer's fields

Field	Type	Description
`id`	string
`reviewerName`	string
`reviewerPhotoUrl`	string or null
`rating`	integer	1–5 stars (0 when Google gave none).
`comment`	string
`postedAt`	string (date-time)
`editedAt`	string (date-time)
`reply`	string or null	The business's public reply, when there is one.
`repliedAt`	string (date-time) or null
`customerId`	string or null
`customer`	object or null
`customer.id`	string
`customer.name`	string
`location`	object
`location.id`	string
`location.title`	string

Sync reviews now

POST /organizations/{organizationId}/reviews/sync

Pulls the followed locations' reviews from Google now (it also happens every six hours). 409 when Google isn't connected. Rate-limited.


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

Example

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

Response

200: the answer's fields

Field	Type	Description
`locations`	integer
`added`	integer
`updated`	integer

Follow a location's reviews

PATCH /organizations/{organizationId}/reviews/locations/{reviewLocationId}

selected: true follows the Business Profile location's reviews (synced, listed, counted); false stops. Answers the overview.


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

Parameters

Name	In	Type	Required	Description
`reviewLocationId`	path	string	Yes

Request body

Field	Type	Required	Description
`selected`	boolean	Yes

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/reviews/locations/{reviewLocationId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selected":true}'

Response

200: the answer's fields

Field	Type	Description
`google`	object
`google.mode`	enum	unconfigured: this server has no Google OAuth client. One of `live`, `fake`, `unconfigured`.
`google.connected`	boolean
`google.status`	string
`google.account`	string or null	The Google account the Business Profile is managed with.
`google.connectedAt`	string (date-time) or null
`google.lastSyncAt`	string (date-time) or null
`google.lastError`	string or null
`locations`	array of object
`locations[].id`	string
`locations[].title`	string
`locations[].address`	string
`locations[].reviewUrl`	string or null	Where customers write a review of this location.
`locations[].selected`	boolean	Reviews are followed for selected locations.
`locations[].lastSyncedAt`	string (date-time) or null
`locations[].lastError`	string or null
`summary`	object
`summary.count`	integer
`summary.average`	number or null
`summary.distribution`	array of integer	Counts of 1, 2, 3, 4 and 5-star reviews.
`summary.unanswered`	integer
`summary.last30Days`	integer

Draft a reply

POST /organizations/{organizationId}/reviews/items/{reviewId}/draft-reply

A reply to edit before posting, written by Claude from the review (and the matched customer's last job), or a polite template without an AI key. Nothing is posted. Rate-limited.


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

Parameters

Name	In	Type	Required	Description
`reviewId`	path	string	Yes

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/reviews/items/{reviewId}/draft-reply" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`draft`	string
`source`	enum	One of `AI`, `TEMPLATE`.

Reply to a review

POST /organizations/{organizationId}/reviews/items/{reviewId}/reply

Public: posts (or replaces) the business's reply on Google, where anyone can read it. Emits review.replied. 409 when Google isn't connected or refuses.


Permission	`reviews.manage` (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	`reviews_reply` (toolset `marketing`)
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
`reviewId`	path	string	Yes

Request body

Field	Type	Required	Description
`comment`	string	Yes	Up to 4000 characters.

Example

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

Response

200: the answer's fields

Field	Type	Description
`id`	string
`reviewerName`	string
`reviewerPhotoUrl`	string or null
`rating`	integer	1–5 stars (0 when Google gave none).
`comment`	string
`postedAt`	string (date-time)
`editedAt`	string (date-time)
`reply`	string or null	The business's public reply, when there is one.
`repliedAt`	string (date-time) or null
`customerId`	string or null
`customer`	object or null
`customer.id`	string
`customer.name`	string
`location`	object
`location.id`	string
`location.title`	string

Remove a reply

DELETE /organizations/{organizationId}/reviews/items/{reviewId}/reply

Removes the business's public reply from Google. 409 when there is none.


Permission	`reviews.manage` (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	`reviews_deleteReply` (toolset `marketing`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

Name	In	Type	Required	Description
`reviewId`	path	string	Yes

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/reviews/items/{reviewId}/reply" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`id`	string
`reviewerName`	string
`reviewerPhotoUrl`	string or null
`rating`	integer	1–5 stars (0 when Google gave none).
`comment`	string
`postedAt`	string (date-time)
`editedAt`	string (date-time)
`reply`	string or null	The business's public reply, when there is one.
`repliedAt`	string (date-time) or null
`customerId`	string or null
`customer`	object or null
`customer.id`	string
`customer.name`	string
`location`	object
`location.id`	string
`location.title`	string

Start connecting Google

POST /organizations/{organizationId}/reviews/google/connect

Grants access: returns Google's consent URL for the Business Profile (business.manage). Google then redirects to /integrations/google/callback with code and state; finish with POST /reviews/google/callback. 400 when this server has no Google OAuth client.


Permission	`integrations.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	`reviews_googleConnect` (toolset `marketing`)
Approval	Waits for your approval in ServFlo when called with an API key or a connected app: the first call answers `428 APPROVAL_REQUIRED`; once you approve it, repeat the call with the `X-ServFlo-Approval` header. See Approvals.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/reviews/google/connect" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`authorizeUrl`	string
`mode`	enum	One of `live`, `fake`, `unconfigured`.

Disconnect Google

POST /organizations/{organizationId}/reviews/google/disconnect

Revokes access: revokes and forgets the Google tokens. Synced reviews and locations stay; reconnect to sync again.


Permission	`integrations.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	`reviews_googleDisconnect` (toolset `marketing`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/reviews/google/disconnect" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`google`	object
`google.mode`	enum	unconfigured: this server has no Google OAuth client. One of `live`, `fake`, `unconfigured`.
`google.connected`	boolean
`google.status`	string
`google.account`	string or null	The Google account the Business Profile is managed with.
`google.connectedAt`	string (date-time) or null
`google.lastSyncAt`	string (date-time) or null
`google.lastError`	string or null
`locations`	array of object
`locations[].id`	string
`locations[].title`	string
`locations[].address`	string
`locations[].reviewUrl`	string or null	Where customers write a review of this location.
`locations[].selected`	boolean	Reviews are followed for selected locations.
`locations[].lastSyncedAt`	string (date-time) or null
`locations[].lastError`	string or null
`summary`	object
`summary.count`	integer
`summary.average`	number or null
`summary.distribution`	array of integer	Counts of 1, 2, 3, 4 and 5-star reviews.
`summary.unanswered`	integer
`summary.last30Days`	integer

Customer feedback

GET /organizations/{organizationId}/feedback

What customers said when they paid, newest first, with the customer, invoice, job and technicians; filter by technician or stars. summary: how many were asked and answered, the average, the stars, how many went on to Google, and each technician's average. Read-only.


Permission	`reviews.read` (Owner, Admin, Dispatcher, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`feedback_list` (toolset `customers`)

Parameters

Name	In	Type	Required	Description
`technicianId`	query	string	No
`rating`	query	integer	No	1–5.
`limit`	query	integer	No	1–200.

Example

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

Response

200: the answer's fields

Field	Type	Description
`items`	array of object
`items[].id`	string
`items[].rating`	integer	1–5 stars.
`items[].comment`	string or null
`items[].submittedAt`	string (date-time) or null
`items[].source`	string or null	Where the customer answered (pay page, receipt …).
`items[].postedToGoogle`	boolean
`items[].customer`	object
`items[].customer.id`	string
`items[].customer.name`	string
`items[].invoice`	object
`items[].invoice.id`	string
`items[].invoice.identifier`	string	INV-n
`items[].job`	object or null
`items[].job.id`	string
`items[].job.identifier`	string	JOB-n
`items[].technicians`	array of object
`items[].technicians[].id`	string
`items[].technicians[].name`	string
`summary`	object
`summary.count`	integer	Answers.
`summary.average`	number or null	Average stars; null without answers.
`summary.stars`	array of integer	How many gave 1, 2, 3, 4 and 5 stars.
`summary.postedToGoogle`	integer
`summary.asked`	integer	Feedback links made (asked).
`summary.byTechnician`	array of object
`summary.byTechnician[].technicianId`	string
`summary.byTechnician[].name`	string
`summary.byTechnician[].count`	integer
`summary.byTechnician[].average`	number

On this page