R2R API Overview

The Respond to Reviews (R2R) API lets partners respond to Yelp reviews on behalf of business owners. This guide covers the full integration flow: finding business IDs, authenticating via OAuth, retrieving reviews, and posting responses.

Integration Overview

There are two paths to get started depending on whether you're discovering businesses via search or pulling the business owner's already-claimed list. Both paths converge at the same review retrieval and response steps.

Path A — Search-based discovery

Search for location on Yelp → Fusion API → Capture biz_ids → Subscribe to biz_ids (YELP_KNOWLEDGE & WEBHOOK) → Retrieve reviews → Respond

Path B — OAuth-based discovery

Business owner completes OAuth → Retrieve claimed biz_ids → Subscribe to biz_ids (YELP_KNOWLEDGE & WEBHOOK) → Retrieve reviews → Respond

Step 1: Find Business IDs

Use the Fusion API to search for business IDs. Three endpoints are available, ordered from most to least precise:

Prefer Phone Search or Biz Match when you have structured location data. Use Biz Search as a fallback for keyword-based discovery.

Step 2: Authenticate with OAuth

OAuth Scopes

Request both r2r and r2r_business_owner for most integrations.

Business Owner Eligibility

Before a business owner can respond to reviews, three conditions must be met. Use the scopes in parentheses to verify each:

• Accepted name — check with r2r_business_owner
• Accepted profile photo — check with r2r_business_owner
• Claimed access to the location — check with r2r

Business owners can update their name and photo at biz.yelp.com.

Step 3: Retrieve Reviews

Once you have biz_ids and the business owner's OAuth token, retrieve reviews via the Get Reviews endpoint or subscribe to webhooks to receive them in real time.

• Get Reviews →
• Guide to webhooks →
• Subscribe to webhooks →

Step 4: Respond to a Review

The response flow includes a claiming check before posting a response:

1. Get business owner's permission via OAuth
2. Check whether the owner has claimed the biz_id
   • Claimed → proceed to step 3
   • Not claimed → route the owner to biz.yelp.com to claim, then return to step 2
3. Retrieve reviews (via API or webhooks)
4. Post response

• Respond to Review endpoint →
• Retrieve Claimed Businesses →
• Retrieve Business Owner Info →

Get Business Details

Use the GET business details endpoint to pull basic attributes for a known biz_id.

Fusion API — GET business details

• Get info for a biz_id →

API Authentication Reference

Two types of credentials are used in this integration depending on the operation:

Review Object: Data Sample

The following is a representative sample of the private reviews API response. Field names and structure reflect real data; values are dummy data.

{
  "time_created": "2022-11-02 12:56:23",
  "id": "26v411ekbbfzHpkuuuYE9g",
  "rating": 3,
  "text": "Solid place to go for fun…, excited to try other things next time we come back.",
  "url": "https://www.yelp.com/biz/acme...",
  "user": {
    "name": "Frank R.",
    "image_url": "https://s3-media2.fl.yelpcdn.com/photo/62MilenvVqbYsa_X-mOe0g/o.jpg",
    "id": "pmk-ront5-26cjzsMtr6pr"
  },
  "public_response": {
    "text": "Thanks for letting us know about your experience. We hope to see you again soon\r\nAcme Co Guest Relations",
    "time_created": "2022-11-03T11:51:13+00:00",
    "business_user": {
      "name": "Bill P.",
      "role": "OWNER",
      "photo_url": "https://s3-media1.fl.yelpcdn.com/buphoto/abvwwWY261349J8LWa-b1w/o.jpg"
    }
  }
}

Testing

Yelp provides two test businesses with a shared business owner account for sandbox testing.

Test business IDs:

• vsI-zHdG7cFQzpGsyxpQnA
• tZAv8Bs6rWuRH2M2FKkVuA

Yelp will grant you a single business owner account with access to both locations. If you don't already have a business owner account, you'll receive an automated email to confirm it. You'll also need to add a profile photo before you can post responses — add one here.

Do

• Post a real, professional response to one review (pick a single review_id)
• Example: "Thanks so much for taking the time to leave your feedback. We'll be sure to review with the manager. Hope to see you again soon."
• Subscribe to a few real businesses to test webhook delivery (receive the webhook, retrieve the review)

Don't

• Don't respond to every review that doesn't already have a response
• Don't post humorous or placeholder responses
• Don't post your own reviews to the test pages
• Don't respond to reviews on real businesses until you've formally launched

Documentation

Full reference at docs.developer.yelp.com. Most-used links:

• OAuth flow guide
• Webhooks guide
• Business Subscriptions API (webhooks)
• Subscribe to webhooks
• Get Reviews
• Respond to Review
• Retrieve Claimed Businesses
• Retrieve Business Owner Info
• Get business details

Next Steps

Partner

• Create a Fusion API account: Log in with an existing Yelp consumer account (or create one), create an app, grab your API key, and email Yelp your client_id
• Configure webhooks: Set up a URL for Yelp to send updates to, then send that URL to Yelp to activate it
• OAuth setup: Send Yelp a list of redirect URIs you'll use — these need to be allowlisted before going live
• Schedule a demo: Once integrated, review your build with the Yelp team before launch

Yelp

• Configure your Fusion API account
• Issue OAuth credentials (client_id and secret)

Appendix: Creating a Fusion API Key

1. Go to Manage API Access in the Fusion portal
2. Sign in with a Yelp consumer account (this is different from a biz.yelp.com account)
3. If you see a pricing or tier notice, you can ignore it — Yelp will opt you out. Click any Get started button to proceed
4. Select Create a New App and fill in the relevant information about your integration
5. After app creation, you'll see your client_id and API key
   • Send your client_id to Yelp
   • Keep your API key private