Skip to main content
Google Business reviews are handled through an async import flow. You queue an import, poll status, then work with normalized review records in our API.

​
How it works

This is an asynchronous job, same idea as Post History Import:
  1. Start: Trigger an import (“Fetch 50 reviews for this location”).
  2. Wait: We fetch from Google and process the batch.
  3. Poll: Check import status.
  4. Fetch: Read imported reviews from the reviews endpoint.
  5. Reply: Create/update/delete owner replies.

​
Step 1: Start the Import

Endpoint: POST /api/v1/misc/google-business/reviews/import 
{
  "teamId": "team_123",
  "count": 50
}

​
Rules & Limits

  • count range: 1-100 per request.
  • One active import per social account: if one is already running, you’ll get 409.
  • Monthly limit per social account (default):
    • Free: 5 reviews / month
    • Pro: 100 reviews / month
    • Business: 250 reviews / month
These are defaults. Organizations can have custom review-import limits configured.

​
Step 2: Check Import Status

Endpoints:
  • GET /api/v1/misc/google-business/reviews/import?teamId=team_123
  • GET /api/v1/misc/google-business/reviews/import/:importId
The list endpoint returns up to 20 latest imports for that team/location, newest first.

​
Statuses

  • PENDING: Waiting in queue.
  • FETCHING_REVIEWS: Import is running.
  • COMPLETED: Finished.
  • FAILED: Import failed after retries.
  • RATE_LIMITED: Temporarily paused due to API/rate pressure; resumes automatically after rateLimitResetAt.
Example import object: 
{
  "id": "imp_abc123",
  "teamId": "team_123",
  "socialAccountId": "sa_123",
  "requestedCount": 50,
  "status": "FETCHING_REVIEWS",
  "reviewsImported": 24,
  "error": null,
  "rateLimitResetAt": null,
  "startedAt": "2026-02-17T10:00:00.000Z",
  "completedAt": null,
  "createdAt": "2026-02-17T09:59:55.000Z",
  "updatedAt": "2026-02-17T10:00:08.000Z",
  "deletedAt": null
}

​
Step 3: Fetch Imported Reviews

Endpoints:
  • GET /api/v1/misc/google-business/reviews?teamId=team_123&limit=50&offset=0
  • GET /api/v1/misc/google-business/reviews/:reviewId?teamId=team_123

​
Query Parameters (GET /reviews)

ParameterTypeDefaultDescription
teamIdstringrequiredTeam ID
limitnumber50Page size (1-100)
offsetnumber0Pagination offset
Example response: 
{
  "reviews": [
    {
      "id": "rev_123",
      "socialAccountId": "sa_123",
      "teamId": "team_123",
      "externalReviewId": "accounts/123/locations/456/reviews/789",
      "reviewerDisplayName": "Jane Doe",
      "reviewerProfilePhotoUrl": "https://lh3.googleusercontent.com/...",
      "starRating": "FIVE",
      "comment": "Amazing service, will come back!",
      "reviewReplyComment": "Thanks a lot for your feedback!",
      "reviewReplyUpdatedAt": "2026-02-17T12:15:00.000Z",
      "createTime": "2026-02-16T18:22:00.000Z",
      "updateTime": "2026-02-17T12:15:00.000Z",
      "importedAt": "2026-02-17T12:15:02.000Z",
      "createdAt": "2026-02-17T12:15:02.000Z",
      "updatedAt": "2026-02-17T12:15:02.000Z",
      "deletedAt": null
    }
  ],
  "total": 1,
  "limit": 100,
  "remainingCapacity": 99
}
starRating values: ONE, TWO, THREE, FOUR, FIVE. limit in this response is your monthly import cap for that social account (not the page size).

​
Step 4: Reply to Reviews

​
Create or Update Reply

Endpoint: PUT /api/v1/misc/google-business/reviews/:reviewId/reply 
{
  "teamId": "team_123",
  "comment": "Thank you for visiting us!"
}
comment length: 1-4096 chars.

​
Delete Reply

Endpoint: DELETE /api/v1/misc/google-business/reviews/:reviewId/reply 
{
  "teamId": "team_123"
}
Both endpoints return the updated review object.

​
Quirks & Gotchas

​
Incremental Sync (No Duplicate Spam)

Re-running imports is safe. Reviews are upserted by external review ID, so existing reviews are updated instead of duplicated.

​
Overlap Window for Edits

Imports intentionally overlap recent data to catch delayed edits/reply updates from Google. So yes, some recently imported reviews may be re-processed - that’s expected.

​
Temporary RATE_LIMITED Is Normal

When Google slows things down, imports switch to RATE_LIMITED and auto-resume. No manual retry endpoint needed for this path.

​
Capacity Is Per Social Account

remainingCapacity is calculated per connected Google Business social account, not globally across all accounts.