📘

This is a Yelp Partner API

Access is disabled by default. See Yelp Partner APIs on how to get access.

Overview

The Yelp Leads API provides a means for Yelp partners to get notified, read and respond to Leads generated by Yelp users, such as conversations.

Access to the Leads API is currently limited to Yelp advertising and listing management reseller partners. Participation in these partnerships is subject to a minimum spend requirement. If you're interested in becoming a reseller partner to access the Leads API, please inquire on those pages for more information. For those who are not reseller partners, we recommend utilizing our Zapier integration—a no-code solution that connects Yelp to your existing software and typically takes less than an hour to set up.

The partners will need to setup authorization and webhooks before they can use the APIs. Each of these setups are explained in detail in the next sections. Please note the Leads API does not support "Message the business", if a Yelp profile page has that, they won't be eligible to use the Leads API.

📘

Ready to integrate?

See the Partner Integration Guide for end-to-end setup instructions including authentication walkthroughs, webhook configuration, email masking, testing environments, and go-live requirements.

Once the initial authentication and webhook setups are done, the partners will get notified about every new interaction for the businesses they have subscribed to (see Business Subscriptions API with type WEBHOOK). They can use the Read APIs (Get Lead/ Get Interaction events) to get the full list of interaction events for a particular lead. The Write APIs enable the partners to mark a lead as read, reply to a lead, and mark a lead as replied outside of Yelp.

Video Walkthrough

To familiarize with the technical data flow, check out our video walkthrough here.

Business Requirements

Please note that you can only get leads data for businesses that are currently advertising on Yelp.

Authorization

Webhooks

Webhooks are used to notify the partner about a new lead, or a new interaction in an existing lead, for a given business. Follow the guide below to learn more about the leads webhooks.

Rate Limiting

All the Leads API endpoints have a default rate limit of 5 requests per second per client per endpoint. There is also a daily request limit per client (default 500 requests/day, though partner integrations are typically provisioned higher). Both limits are configurable — contact us to know more. For detailed error handling and retry recommendations, see the Partner Integration Guide.

API Endpoints

The Leads API exposes endpoints for different use cases. Follow the links below to know more about each endpoint.

• Get Lead
• Get Lead Events
• Get Lead IDs for a Business
• Write Event
• Mark Lead as replied
• Mark Lead Event as read

FAQs

What's Next

• Partner Integration Guide — Step-by-step setup for authentication, webhooks, email masking, testing, and go-live
• OAuth Authorization — Configure OAuth for your integration
• Leads Webhooks — Set up webhooks to receive lead notifications
• Leads API FAQs — Common questions and troubleshooting