Reviews API

REST endpoints for reviews in SKUFlow: 11 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.skuflow.ai/api. Every call needs Authorization: Bearer skf_… (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, Staff, Member)
Risk	`read`, OAuth scope `skuflow.read`. Read: reads only.
MCP tool	`reviews_overview` (toolset `marketing`)

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews" \
  -H "Authorization: Bearer $SKUFLOW_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, Staff, Member)
Risk	`read`, OAuth scope `skuflow.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.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews/items" \
  -H "Authorization: Bearer $SKUFLOW_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, Staff, Member)
Risk	`read`, OAuth scope `skuflow.read`. Read: reads only.
MCP tool	`reviews_get` (toolset `marketing`)

Parameters

Name	In	Type	Required	Description
`reviewId`	path	string	Yes

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews/items/{reviewId}" \
  -H "Authorization: Bearer $SKUFLOW_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, Staff)
Risk	`write`, OAuth scope `skuflow.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`reviews_sync` (toolset `marketing`)
Plan	Google reviews: the Grow plan and up.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews/sync" \
  -H "Authorization: Bearer $SKUFLOW_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, Staff)
Risk	`write`, OAuth scope `skuflow.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`reviews_setLocation` (toolset `marketing`)
Plan	Google reviews: the Grow plan and up.

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.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews/locations/{reviewLocationId}" \
  -H "Authorization: Bearer $SKUFLOW_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, or a polite template without an AI key. Nothing is posted. Rate-limited.


Permission	`reviews.manage` (Owner, Admin, Staff)
Risk	`write`, OAuth scope `skuflow.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`reviews_draftReply` (toolset `marketing`)
Plan	Google reviews: the Grow plan and up.

Parameters

Name	In	Type	Required	Description
`reviewId`	path	string	Yes

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews/items/{reviewId}/draft-reply" \
  -H "Authorization: Bearer $SKUFLOW_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, Staff)
Risk	`sensitive`, OAuth scope `skuflow.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`reviews_reply` (toolset `marketing`)
Plan	Google reviews: the Grow plan and up.
Approval	Over MCP, this tool asks for your OK first (in the AI app when it supports it, otherwise in SKUFlow). 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.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews/items/{reviewId}/reply" \
  -H "Authorization: Bearer $SKUFLOW_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, Staff)
Risk	`sensitive`, OAuth scope `skuflow.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`reviews_deleteReply` (toolset `marketing`)
Plan	Google reviews: the Grow plan and up.
Approval	Over MCP, this tool always waits for your approval in SKUFlow. See Approvals.

Parameters

Name	In	Type	Required	Description
`reviewId`	path	string	Yes

Example

curl -X DELETE "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews/items/{reviewId}/reply" \
  -H "Authorization: Bearer $SKUFLOW_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 `skuflow.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`reviews_googleConnect` (toolset `marketing`)
Plan	Google reviews: the Grow plan and up.
Approval	Waits for your approval in SKUFlow 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-SKUFlow-Approval` header. See Approvals.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews/google/connect" \
  -H "Authorization: Bearer $SKUFLOW_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 `skuflow.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 SKUFlow. See Approvals.

Example

curl -X POST "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/reviews/google/disconnect" \
  -H "Authorization: Bearer $SKUFLOW_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 and invoice; filter by stars. summary: how many were asked and answered, the average, the stars and how many went on to Google. Read-only.


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

Parameters

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

Example

curl "https://app.skuflow.ai/api/organizations/$ORGANIZATION_ID/feedback" \
  -H "Authorization: Bearer $SKUFLOW_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
`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).

Reviews overviewCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

List reviewsCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

A reviewCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Sync reviews nowCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Follow a location's reviewsCopy Anchor Link

ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Draft a replyCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Reply to a reviewCopy Anchor Link

ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Remove a replyCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Start connecting GoogleCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Disconnect GoogleCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Customer feedbackCopy Anchor Link

ParametersCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

On this page

Reviews overview

Example

Response

List reviews

Parameters

Example

Response

A review

Parameters

Example

Response

Sync reviews now

Example

Response

Follow a location's reviews

Parameters

Request body

Example

Response

Draft a reply

Parameters

Example

Response

Reply to a review

Parameters

Request body

Example

Response

Remove a reply

Parameters

Example

Response

Start connecting Google

Example

Response

Disconnect Google

Example

Response

Customer feedback

Parameters

Example

Response