Skip to main content
SocialAPI’s reviews API lists the reviews left on a connected business location or app, reports its rating summary, and posts the business’s public reply. Google Business Profile and App Store Connect have reviews. A call for an account on any other platform returns 422 account.platform_unsupported. A reply costs 1 interaction credit, and reads cost nothing. Google moderates every reply: a reply is accepted first and goes live only after Google approves it. An App Store Connect reply returns no state, and can take up to 24 hours to appear on the App Store.

Endpoints

Reviews cannot be created or deleted through the API, and a reply cannot be edited or deleted. To change a reply, send a new one: a review has 1 business reply, and a new reply replaces it.

The two list endpoints

The two GET endpoints answer different questions.
  • GET /v1/inbox/reviews returns 1 row per review-capable account: its name, average rating, review count, and the time of its newest review. Use it to build a list of locations and apps. Add platform=google or platform=app_store_connect to filter.
  • GET /v1/inbox/reviews/{account_id} returns the reviews of the 1 account you name. Use it to read, sort, and page through them.
Response (HTTP 200):
status is ok, reconnection_required (the account needs reconnecting), or error (the platform refused the request or did not answer in time). The rating fields and last_review_at are null unless status is ok. A failing account never fails the whole list.

List the reviews of an account

Response (HTTP 200):
summary covers the whole location or app, not the page. Every field of a review, including media and reply_url, is in Google Business Profile reviews. App Store Connect reviews also carry title, the reviewer’s headline, and report an average_rating of 0: see App Store Connect reviews. Paging follows Pagination.

Reply to a review

Response (HTTP 200):
{review_id} is the review’s sapi_rev_ ID or the platform’s review ID. account_id and text are required: a missing one returns 400 validation.field_required. state is the reply’s moderation state on Google. App Store Connect returns no state.
On Google Business Profile, a successful reply is not yet published. success: true means Google accepted the reply for review. Nobody can see it until its state is APPROVED. On App Store Connect, the reply returns no state and can take up to 24 hours to appear on the App Store.

Moderation of replies

Google moderates replies, so a reply moves through 3 states. SocialAPI sends a review.updated event when Google decides, with change set to reply_approved or reply_rejected. You can also read the review again and check reply.state. After a rejection, send a new reply that passes Google’s content rules. Google Business Profile reviews explains them.

Platform support

Google Business Profile and App Store Connect have reviews. SocialAPI does not read Facebook reviews (Meta deprecated Page recommendations in Graph API v22.0), Instagram has none, and Trustpilot is not available in SocialAPI: see Trustpilot. The capability matrix shows every platform. Google’s connect rules, location data, and review limits are in Google Business Profile reviews, and App Store Connect’s in App Store Connect.

Limits

Errors and debugging

Check these in order when a review call fails:
  1. 401, 403 auth.insufficient_scope. Your SocialAPI API key is invalid, or a scoped key lacks the scope in Scopes.
  2. 401 platform.app_store_connect.unauthorized, 403 platform.app_store_connect.forbidden, 429 platform.app_store_connect.rate_limit. App Store Connect rejected the App Store Connect API key, refused its role, or the key’s hourly limit is used up. See App Store Connect review errors.
  3. 404 account.not_found, 403 account.reconnection_required. The acc_ ID is not yours, or the account needs reconnecting.
  4. 403 account.permission_missing. The account lacks the permission the call needs: reviews.read to list the reviews of an account, and reviews.write to reply. error.meta.permission names it.
  5. 422 account.platform_unsupported. The account’s platform has no reviews.
  6. 400 validation.id_invalid, 400 validation.id_platform_mismatch. The review ID is not a review ID, or it belongs to another platform.
  7. 400 validation.field_required, 400 validation.field_invalid. account_id or text is missing, or limit or order is wrong.
  8. 429 validation.interaction_limit_exhausted. The plan’s interaction allowance is used up.
The full catalog is in Errors.

Scopes

Events

SocialAPI sends review.received when a customer posts a new review and review.updated when a review changes or Google decides on a reply. Both are for Google Business Profile, and an account without the reviews.read permission receives neither. Google can miss a notification and does not replay it, so read GET /v1/inbox/reviews/{account_id} on a schedule to fill any gap.

Use from an AI agent

SocialAPI has no endpoint to delete a business reply. See MCP tools.
Last modified on November 15, 2026