Search

GET https://api.yelp.com/v3/businesses/search

The endpoint has been upgraded to return businesses which support Yelp Reservations.

The three parameters that must be passed in to find reservations are reservation_time, reservation_date, and reservation_covers.

Sample query that will return Thai Restaurants in San Francisco that accept Yelp reservations:
https://api.yelp.com/v3/businesses/search?location=San%20Francisco&term=Thai&attributes=reservation

Parameters

Exceptions

The response will mostly match our public search response, see https://www.yelp.com/developers/documentation/v3/business_search.

Searching for reservations adds an additional field, the "data" field. This will contain additional reservation times that are + or - 30 minutes from the requested reservation time.

Response

Sample response of with data field (public data trimmed for brevity):

# … trimmed
		{
			"id": "cuisine-of-nepal-san-francisco",
			"name": "Cuisine of Nepal",
			"image_url": ...,
			"is_closed": false,
			"url": ...,
			"review_count": 303,
			"categories": [...],
			"rating": 4.5,
			"coordinates": {...},
			"transactions": [
				"delivery",
				"pickup",
				"restaurant_reservation"
			],
			"price": "$$",
			"location": {...},
			"phone": "+14156472222",
			"display_phone": "(415) 647-2222",
			"distance": 2502.5961202999997,
			"attributes": {
				"gender_neutral_restrooms": true
			},
			"data": {
				"reservation_openings": [
					"13:30",
					"13:45",
					"14:00"
				]
			}
		},
# … trimmed

Openings endpoint

GET https://api.yelp.com/v3/bookings/{business-id}/openings

To get the available reservation times for a restaurant, you can give this endpoint the Business ID along with a few parameters. This endpoint will return times around the requested timeslot and across several days to provide the end user with some options.

In general, the openings endpoint will return times across 4 days - the day before, current day and 2 days after the requested date.

Currently, Yelp Reservations API does not support reservations which require a credit card. So, if "credit_card_required": true is returned, you should NOT proceed to the Holds endpoint. If you do, the Holds endpoint will return a null hold_id.

Parameters

Exceptions

Response

Sample Request

curl -X GET \
'https://api.yelp.com/v3/bookings/victors-french-bistro-test-listing-san-francisco/openings?covers=2&date=2017-12-30&time=18%3A00' \
-H 'Authorization: Bearer {ACCESS_TOKEN}'

Sample Response

{
  "reservation_times": [
    {
      "date": "2017-09-22",
      "times": [
	   {
	     "credit_card_required": true,
	     "time": "14:45",
	     "url":  
  "https://www.devc.yelpreservations.com/r/dorsia/reserve/2017-09-22/1445/3/"
	   },
	   {
	     "credit_card_required": true,
	     "time": "15:00",
	     "url":  
  "https://www.devc.yelpreservations.com/r/dorsia/reserve/2017-09-22/1500/3/"
	   },
	   {
	     "credit_card_required": true,
	     "time": "15:15",
	     "url": 
  "https://www.devc.yelpreservations.com/r/dorsia/reserve/2017-09-22/1515/3/"
	   },
      ]
    },
    {
      "date": "2017-09-23",
      "times": [
	 {
	     "credit_card_required": true,
	     "time": "14:45",
	     "url": 
  "https://www.devc.yelpreservations.com/r/dorsia/reserve/2017-09-23/1445/3/"
	   },
	   {
	     "credit_card_required": true,
	     "time": "15:00",
	     "url": 
  "https://www.devc.yelpreservations.com/r/dorsia/reserve/2017-09-23/1500/3/"
	   },
	   {
	     "credit_card_required": true,
	     "time": "15:15",
	     "url": 
  "https://www.devc.yelpreservations.com/r/dorsia/reserve/2017-09-23/1515/3/"
	   },
      ]
    },
  ]
  "covers_range": {
    "min_party_size": 1,
    "max_party_size": 7
  }
}

Holds endpoint

POST https://api.yelp.com/v3/bookings/{business_id}/holds

This endpoint will place a temporary hold on the requested time slot so that the partner can request all the required reservation information from the user. Holds are only valid for 5 minutes and you must use the hold id returned from this endpoint to place the reservation or you will get a conflict.

Note: All parameters being sent into the holds endpoint needs to be sent as form data inside of the request body. They will not work as query parameters.

Parameters

Exceptions

Response

Sample Request

curl -X POST \
'https://api.yelp.com/v3/bookings/victors-french-bistro-test-listing-san-francisco/holds' \
  -H 'authorization: Bearer {ACCESS_TOKEN}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'covers=2&date=2017-12-30&time=18%3A00&unique_id=tmL95Scg93sajOswiIl4kA'

Sample Response

{
	"cancellation_policy": "Cancel before it’s too late!",
	"credit_card_hold": false,
	"expires_at": 1506118155.568123,
	"hold_id": "KiXJLFFBnwW6NJbK34uKBQ",
	"is_editable": false,
	"last_cancellation_date": 1506106800.0,
	"notes": "Join us for Happy Hour.",
	"reserve_url": "https://www.yelp.com/reservations/aeJKOHWHK-z9ALQVTZj_Jw/checkout/2017-09-23/1200/3?hold_id=23774490"
}

Reservations endpoint

POST https://api.yelp.com/v3/bookings/{business_id}/reservations

With this endpoint, you can place a physical reservation at a restaurant with all the information provided. This endpoint will take an optional hold id if the partner previously placed a hold. If the restaurant requires a credit card hold, you will not be able to place a reservation and the API will return an error.

In this case, you should use the reserve_url provided in the hold endpoint or the opening endpoint to prompt the user for a reservation.

Note: All parameters being sent into the reservations endpoint needs to be sent as form data inside of the request body. They will not work as query parameters. Additionally, you will receive an error if you don’t pass the exact same reservation time, date and covers values as you supplied to the Holds endpoint.

Parameters

Exceptions

Response

Sample Request

curl -X POST \
'https://api.yelp.com/v3/bookings/victors-french-bistro-test-listing-san-francisco/reservations' \
  -H 'authorization: Bearer {ACCESS_TOKEN}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'covers=2&date=2017-12-30&time=18%3A00&unique_id={UNIQUE_ID}&hold_id={HOLD_ID}&first_name={FIRST_NAME}&last_name={LAST_NAME}&email={EMAIL}&phone={PHONE}&notes={NOTES}'

Sample Response

{
	"confirmation_url": "https://www.yelp.com/reservations/dorsia-san-francisco-6/confirmed/36dbba9e-14a9-43f3-942d-7fdeddda74fc?checkout_success=1&adjust_creative=CPEhJkVcrc5wVgsRVvhEZQ&utm_campaign=yelp_api_v3&utm_medium=api_v3_reservations&utm_source=CPEhJkVcrc5wVgsRVvhEZQ",
	"notes": "reservation password: leprechaun"
	"reservation_id": "e33b40ef-f6b1-4f17-987c-d850892564b",
}

Status endpoint

GET https://api.yelp.com/v3/bookings/reservation/{reservation_id}/status

Parameters

Exceptions

Response

Sample Request

curl -X GET \
'https://api.yelp.com/v3/bookings/reservation/e33b40ef-f6b1-4f17-987c-d850892564b/status \
  -H 'authorization: Bearer {ACCESS_TOKEN}'

Sample Response

{
  "active": true,
  "date": "2017-12-30",
  "time": "11:00:00",
  "covers": 3
}

Cancel endpoint

POST https://api.yelp.com/v3/bookings/reservation/{reservation_id}/cancel

The cancel endpoint allows you to cancel a reservation using a reservation_id.

Parameters

Exceptions

Response

This endpoint returns an empty response.

Sample Request

curl -X POST \
'https://api.yelp.com/v3/bookings/reservation/e33b40ef-f6b1-4f17-987c-d850892564b/cancel \
  -H 'authorization: Bearer {ACCESS_TOKEN}'

Sample Response

{}