Synup
Create a key
GuideGuides/Recipes/Respond to a review
How do I respond to a review through the API?

Respond to a Review via API

Post an owner reply to a review with the Synup API, read the push status back, and know which failures are worth a retry.

At a glance

What this guide accomplishes
Post an owner reply to a review and interpret whether the push to the platform succeeded, queued or failed.
APIs used
Reference
Reviews
Prerequisites
  • An API key with write access
  • The reviewId to reply to
Typical use cases
  • Replying from your own review inbox
  • Sending an approved reply from a queue
  • Automating first-line replies with a human check

POST /api/v1/reviews/reply takes the review id and the reply text, posts the reply under the business's name, and pushes it to the platform the review came from. The response tells you what happened: pushed: true with status: posted when it went out now, pending when it is queued, and a retryable flag when it failed.

curl -X POST https://ai.synup.com/api/v1/reviews/reply \
  -H "Authorization: Bearer $SYNUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewId": "REVIEW_ID",
    "text": "Thank you for letting us know. I am sorry the wait was longer than it should have been. Please call us on 415 555 0142 and ask for Maria so we can make it right."
  }'
const API = "https://ai.synup.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.SYNUP_API_KEY}`,
  "Content-Type": "application/json",
};

async function reply(reviewId, text) {
  const res = await fetch(`${API}/reviews/reply`, {
    method: "POST",
    headers,
    body: JSON.stringify({ reviewId, text }),
  });
  if (res.status === 422) return { status: "not_respondable", error: (await res.json()).error };
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
  return (await res.json()).data; // { ok, pushed, status, externalReplyId, retryable }
}
import os
import requests

API = "https://ai.synup.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SYNUP_API_KEY']}", "Content-Type": "application/json"}

def reply(review_id, text):
    r = requests.post(f"{API}/reviews/reply", headers=HEADERS, timeout=30,
                      json={"reviewId": review_id, "text": text})
    if r.status_code == 422:
        return {"status": "not_respondable", "error": r.json()["error"]}
    r.raise_for_status()
    return r.json()["data"]

A 422 means the review cannot be replied to, almost always because it was removed from its source. A failed push with retryable: true deserves one retry after a pause; with retryable: false, stop and have someone check the platform connection.