REST APIGET

Inbox reviews

List Google Business Profile reviews of your locations by rating and reply state, put or replace the reply, delete it and mark reviews read.

GEThttps://post.adaptlypost.com/post/api/v1/inbox/reviews

Returns Google Business Profile reviews of your locations, newest first. Answers { reviews, total, hasMore, nextCursor }.

API Key (Bearer token)

Permission:inbox.readRoles and permissions

Every role holds inbox.read, so any valid key can read the inbox.

Query parameters

Parameter	Type	Description
`accountIds`	`string[]`	Only these accounts, by the id from GET /social-accounts. Repeat the key or separate values with commas. Up to 50
`platforms`	`PlatformType[]`	Only these platforms. Repeat the key or separate values with commas
`statuses`	`InboxStatus[]`	Only items in these states: UNREAD, READ or DONE. Repeat the key or separate values with commas
`since`	`string (ISO 8601)`	Only items created on the platform at or after this date-time
`search`	`string`	Text to search for
`ratings`	`number[]`	Only reviews with these star ratings, 1 to 5. Repeat the key or separate values with commas
`replied`	`boolean`	true for reviews that have a reply, false for those without one
`limit`	`number`	Items per page, 1 to 100. Default 25
`cursor`	`string`	The nextCursor of the previous page. nextCursor is null on the last page

About 10 minutes, not real time

AdaptlyPost reads each connected account every 10 minutes and keeps what it finds. The lists answer from that copy, so a new comment, mention, message or review shows up within about 10 minutes. POST /api/v1/inbox/refresh asks for a read now. Webhook events come from the same reads.

Channels that need a reconnect

Every channel is open to the API. When a connection lacks the platform permission for a channel or action, including permissions the platform is still reviewing for AdaptlyPost, GET /api/v1/inbox/summary shows the channel as RECONNECT_REQUIRED and every write on it answers 403 inbox_reconnect_required. An expired token answers the same. Ask the user to reconnect the account in AdaptlyPost; retrying does not help.

Review fields

Field	Description
`id`	Review id. Use it with the endpoints below
`accountId`	The account the item belongs to: its id from GET /social-accounts
`platform`	Always GOOGLE_BUSINESS
`accountName`	Display name of that account
`platformReviewId`	Google's id of the review
`reviewer`	name, avatarUrl and isAnonymous. Google hides the name of anonymous reviewers
`rating`	Stars, 1 to 5
`text`	The review text. Can be empty, since a rating alone is a review
`reply`	The location's reply as { text, updatedAt }, or null
`createdAt`	When the review was written
`updatedAt`	When the reviewer last changed it
`status`	UNREAD, READ or DONE. A new review starts UNREAD, or DONE when it already has a reply. An edited review goes back to UNREAD unless it has a reply
`repliedAt`	When your account last replied, or null
`maxReplyLength`	The longest reply Google accepts, in UTF-8 bytes: 4096
`capabilities`	canReply: false when the account must be reconnected

Reply to a review

Google allows one reply per review. Sending a reply replaces the one already there, whether it was written in AdaptlyPost or on Google.

PUThttps://post.adaptlypost.com/post/api/v1/inbox/reviews/:id/reply

Puts the reply on the review, or replaces it, and answers 200 with the review.

API Key (Bearer token)

Permission:inbox.replyRoles and permissions

Writes need inbox.reply (Admin and Editor) and an active AdaptlyPost plan. Without the plan they answer 403 subscription_required.

Body parameters

Parameter	Type	Description
`text`REQUIRED	`string`	The reply, up to 4096 UTF-8 bytes

DELETEhttps://post.adaptlypost.com/post/api/v1/inbox/reviews/:id/reply

Removes the location's reply and answers 200 with the review.

API Key (Bearer token)

Permission:inbox.replyRoles and permissions

Mark as read or done

POSThttps://post.adaptlypost.com/post/api/v1/inbox/reviews/status

Sets the status of up to 100 reviews and answers { reviews, unreadCount }.

API Key (Bearer token)

Permission:inbox.replyRoles and permissions

Body parameters

Parameter	Type	Description
`ids`REQUIRED	`string[]`	1 to 100 ids from the list
`status`REQUIRED	`InboxStatus`	UNREAD, READ or DONE

Refusals

A refused call answers { statusCode, error, code, message }. Branch on code. message explains the refusal in words.

Code	Status	When, and what to do
`inbox_item_not_found`	404	The id does not exist or belongs to another workspace. Stop
`inbox_action_unsupported`	400	The platform, or this item, does not allow this hide, delete or like. capabilities says what applies. Stop
`inbox_reconnect_required`	403	The connection lacks the permission for this channel or action, including one still in platform review, or its token expired. Ask the user to reconnect the account in AdaptlyPost. Do not retry
`inbox_reply_invalid`	400	The text is empty or over the limit. The message names the limit. Fix the text
`inbox_messaging_window_closed`	400	Facebook or Instagram: the 24-hour reply window has passed. Stop
`inbox_rate_limited`	429	The platform rate limited AdaptlyPost. Retry after a while
`inbox_platform_error`	503	The platform failed. Retry later
`permission_denied`	403	The key's role lacks inbox.read or inbox.reply. Do not retry
`subscription_required`	403	A write without an active AdaptlyPost plan. Do not retry

List unanswered low ratings

curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/reviews?ratings=1,2&replied=false' \
  --header 'Authorization: Bearer <api-key>'

Reply to a review

curl --request PUT \
  --url https://post.adaptlypost.com/post/api/v1/inbox/reviews/rvw_0c93b4d1/reply \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "Sorry about the wait, Piotr. We have added a second barista on weekends." }'

Delete a reply

curl --request DELETE \
  --url https://post.adaptlypost.com/post/api/v1/inbox/reviews/rvw_0c93b4d1/reply \
  --header 'Authorization: Bearer <api-key>'

Mark a review as read

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/reviews/status \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "ids": ["rvw_0c93b4d1"], "status": "READ" }'

200

{
  "reviews": [
    {
      "id": "rvw_0c93b4d1",
      "accountId": "conn_gbp_001",
      "platform": "GOOGLE_BUSINESS",
      "accountName": "AdaptlyPost Kraków",
      "platformReviewId": "AbFvOqm4x2...",
      "reviewer": {
        "name": "Piotr K.",
        "avatarUrl": null,
        "isAnonymous": false
      },
      "rating": 2,
      "text": "Good coffee, but a 20 minute wait on Saturday.",
      "reply": null,
      "createdAt": "2026-11-07T12:30:00.000Z",
      "updatedAt": "2026-11-07T12:30:00.000Z",
      "status": "UNREAD",
      "repliedAt": null,
      "maxReplyLength": 4096,
      "capabilities": { "canReply": true }
    }
  ],
  "total": 1,
  "hasMore": false,
  "nextCursor": null
}