--- agentTools: projectIndex: https://docs.developer.yelp.com/llms.txt --- # 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. **cURL example with OAuth authentication:** ```sh 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" ``` **Example 200 response:** ```json { "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" } ``` # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "Reservations API", "version": "1.0" }, "servers": [ { "url": "https://api.yelp.com" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "To authenticate API calls with the API Key, set the Authorization HTTP header value as `Bearer API_KEY`.\n\nExample: `Bearer 23813239889e947efd3e787cc41b0b839f442a85c5bfd30bd4b9a85ec3a54d5cae4d52b37ff52e64deb9c83bd04883812a6cebde04f2f25752f31be0ac74b514`.\n\nYou can create or find your API Key at [yelp.com](https://www.yelp.com/developers/v3/manage_app).\n" } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/v3/bookings/{business_id_or_alias}/holds": { "post": { "summary": "Holds", "tags": [ "Bookings" ], "operationId": "v3_holds", "description": "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.\n\nNote: 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.\n\n**cURL example with OAuth authentication:**\n```sh\n 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\"\n```\n\n**Example 200 response:**\n```json\n{\n \"cancellation_policy\": \"Cancel before it's too late!\",\n \"credit_card_hold\": false,\n \"expires_at\": 1506118155.568123,\n \"hold_id\": \"KiXJLFFBnwW6NJbK34uKBQ\",\n \"is_editable\": false,\n \"last_cancellation_date\": 1506106800.0,\n \"notes\": \"Join us for Happy Hour.\",\n \"reserve_url\": \"https://www.yelp.com/reservations/aeJKOHWHK-z9ALQVTZj_Jw/checkout/2017-09-23/1200/3?hold_id=23774490\"\n}\n```\n", "parameters": [ { "in": "path", "required": true, "name": "business_id_or_alias", "description": "A unique identifier for a Yelp Business. Can be either a 22-character Yelp Business ID, or a Yelp Business Alias.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The request object for placing a temporary hold on a requested time slot.", "properties": { "covers": { "description": "How many people are attending the reservation.", "type": "integer", "minimum": 1, "maximum": 10 }, "date": { "description": "The date for the reservation, format is YYYY-mm-dd", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "description": "The time of the requested reservation, format is HH:MM.", "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "unique_id": { "description": "This should be the user's device id or a unique user id to help tie together actions of the user on the API. Multiple requests to the Holds endpoint by the same user should use the same unique_id.", "type": "string", "maxLength": 300 } }, "required": [ "covers", "date", "time", "unique_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancellation_policy": { "type": "string", "description": "The restaurant's cancellation policy." }, "credit_card_hold": { "type": "boolean", "description": "Whether or not a restaurant requires a credit card hold to place a reservation." }, "expires_at": { "type": "float", "description": "When the hold expires, as a unix timestamp." }, "hold_id": { "type": "string", "description": "The unique Hold ID to use when placing a reservation." }, "is_editable": { "type": "boolean", "description": "Whether or not changes can be made to the reservation." }, "last_cancellation_date": { "type": "float", "description": "The last cancellable date for the reservation, as a unix timestamp." }, "notes": { "type": "string", "description": "Any reservation notes from the restaurant." }, "reserve_url": { "type": "string", "description": "The URL at which to place a reservation in case the restaurant requires a credit card hold." } }, "required": [ "cancellation_policy", "credit_card_hold", "expires_at", "hold_id", "is_editable", "last_cancellation_date", "notes", "reserve_url" ] } } } }, "400": { "description": "This error is returned in any of the following scenarios:\n\n| Status |\terror_code | Reason\n| ------- | ----------------------- | ------------------------------\n| 400 | COVERS_VALUE_OUT_OF_RANGE | This restaurant only accepts online reservations between {minvalue} and {max_value} people. NOTE: The {min_value} and {max_value} will be dependent on the restaurant's accepted minimum and maximum values for their online reservations.\n| 400 | INVALID_DATE_TIME_RANGE | The date time range is invalid\n| 400 | INVALID_RESERVATION_PARAMETER | Bad request\n| 400 | TOO_LARGE_VALIDATION_ERROR | Number too big: {value}\n| 400 | DATE_TIME_VALIDATION_ERROR | Invalid format, expected format is %H:%M\n| 400 | DATE_TIME_VALIDATION_ERROR | Invalid format, expected format is %Y-%m-%d\n| 400 | TOO_SMALL_VALIDATION_ERROR | Number too small: {value}\n| 400 | TOO_LARGE_VALIDATION_ERROR | Number too big: {value}\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "type": "string", "description": "The error code." }, "description": { "type": "string", "description": "The description of the error." } } } } } } } }, "401": { "$ref": "#/paths/~1v3~1private~1reservation_availability~1update/post/responses/401" }, "404": { "description": "This error is returned in any of the following scenarios:\n\n| Status |\terror_code | Reason\n| ------- | ----------------------- | ------------------------------\n| 404 | BUSINESS_NOT_FOUND | The requested business could not be found.\n| 404 | DOES_NOT_TAKE_RESERVATIONS | The given business does not take reservations.\n", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1bookings~1{business_id_or_alias}~1holds/post/responses/400/content/application~1json/schema" } } } }, "409": { "description": "This error is returned in any of the following scenarios:\n\n| Status |\terror_code | Reason\n| ------- | ----------------------- | ------------------------------\n| 409 | HOLD_SLOT_NOT_AVAILABLE |\tThe requested hold time is not available. Please select a different time.\n", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1bookings~1{business_id_or_alias}~1holds/post/responses/400/content/application~1json/schema" } } } }, "429": { "$ref": "#/paths/~1v3~1private~1reservation_availability~1update/post/responses/429" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "examples": { "Internal Server Error": { "value": { "error": { "code": "INTERNAL_ERROR", "description": "Something went wrong internally, please try again later." } } } }, "schema": { "$ref": "#/paths/~1v3~1bookings~1{business_id_or_alias}~1holds/post/responses/400/content/application~1json/schema" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1bookings~1{business_id_or_alias}~1holds/post/responses/400/content/application~1json/schema" }, "examples": { "Service Unavailable": { "value": { "error": { "code": "SERVICE_UNAVAILABLE", "description": "Service Unavailable" } } } } } } } } } }, "/v3/private/reservation_availability/update": { "post": { "summary": "Reservation Availability Update", "tags": [ "Bookings" ], "description": "Push reservation availability data for a venue. Each request contains slot data for one business across one or more dates.\n\n**Key concepts:**\n- **Per-date full replacement:** Each date you send replaces everything Yelp has for that date. No diffs or patches.\n- **Include booked slots:** Send `spots_open: 0` for fully-booked time slots so Yelp can distinguish \"sold out\" from \"closed.\"\n- **15-minute resolution:** Slot times must be on 15-minute boundaries (HH:00, HH:15, HH:30, HH:45).\n- **Timezone derived from venue:** Yelp determines timezone from the business address. Times in the payload are local to the venue.\n\n**Prerequisites:**\n- The venue must be registered via the Data Ingestion API with `service_type_v2` configuration.\n- The `partner_business_id` must match the ID used during DI onboarding.\n\n**Authentication:** Bearer token via OAuth 2.0 client credentials. Your API key must be whitelisted for this endpoint and linked to a partner ID. Contact your Yelp partner integration representative.\n\n**Rate limits:** 50 QPS per partner.\n", "operationId": "reservation_availability_update_v3", "requestBody": { "description": "Availability data for one business", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partner_business_id": { "type": "string", "description": "Unique identifier for the venue in the partner's system (e.g., restaurant ID). Must match the ID used during DI onboarding." }, "service": { "type": "string", "default": "default", "description": "Service identifier. Use \"default\" for standard dining, or a named service_id for experiences." }, "pre_booking_notes": { "type": "string", "nullable": true, "description": "Notes displayed to diners during the booking flow (e.g., dress code, parking info)." }, "seating_areas": { "type": "array", "description": "Seating areas available at this venue. Overrides the areas from DI onboarding for this push.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Seating area identifier matching the IDs used in openings." }, "name": { "type": "string", "description": "Display name for the seating area." } }, "required": [ "id", "name" ] } }, "dates": { "type": "array", "minItems": 1, "maxItems": 90, "description": "Availability for one or more dates. Each date replaces all previously sent data for that date (per-date full replacement).", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Calendar date in YYYY-MM-DD format. Must be today or in the future (up to +90 days)." }, "party_sizes": { "type": "array", "minItems": 1, "description": "Availability grouped by party size. Include all party sizes that have availability for this date.", "items": { "type": "object", "properties": { "party_size": { "type": "integer", "minimum": 1, "description": "Number of covers for this group of openings." }, "openings": { "type": "array", "description": "Available time slots for this party size. Send an empty array to indicate no availability for this party size on this date.", "items": { "type": "object", "properties": { "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):(00|15|30|45)$", "description": "Time of day in HH:MM format on 15-minute boundaries (e.g., \"18:00\", \"18:15\")." }, "spots_open": { "type": "integer", "minimum": 0, "description": "Number of available spots. Use 0 to indicate a fully-booked slot (distinguishes \"sold out\" from \"closed\")." }, "spots_total": { "type": "integer", "minimum": 0, "description": "Total capacity for this slot. Optional. Enables \"X of Y remaining\" display." }, "slot_token": { "type": "string", "maxLength": 256, "description": "Correlation ID echoed back at booking time. Use your internal slot identifier." }, "seating_area_ids": { "type": "array", "maxItems": 10, "items": { "type": "string" }, "description": "Numeric IDs of seating areas where this opening is available. Must match the seating area IDs sent during DI onboarding." }, "requires_cc_hold": { "type": "boolean", "default": false, "description": "Whether a credit card hold is required to book this slot." }, "credit_card_policy_id": { "type": "string", "description": "Credit card policy that applies to this slot. Must match an ID from DI onboarding." }, "bookable_until": { "type": "string", "format": "date-time", "description": "ISO 8601 deadline after which this slot can no longer be booked. Slot is automatically suppressed from search after this time." }, "cancelable_until": { "type": "string", "format": "date-time", "description": "ISO 8601 deadline after which this reservation can no longer be canceled without penalty." }, "duration_minutes": { "type": "integer", "minimum": 15, "maximum": 480, "description": "Slot duration override in minutes (must be a multiple of 15)." }, "visibility": { "type": "string", "enum": [ "online", "inhouse" ], "default": "online", "description": "Booking channel. \"online\" slots appear in search; \"inhouse\" slots are phone-only." } }, "required": [ "time" ] } } }, "required": [ "party_size", "openings" ] } } }, "required": [ "date", "party_sizes" ] } } }, "required": [ "partner_business_id", "dates" ] }, "examples": { "basic": { "summary": "Basic availability push", "value": { "partner_business_id": "1071685", "service": "default", "dates": [ { "date": "2026-08-01", "party_sizes": [ { "party_size": 2, "openings": [ { "time": "18:00", "spots_open": 4 }, { "time": "18:15", "spots_open": 3 }, { "time": "18:30", "spots_open": 5 }, { "time": "19:00", "spots_open": 0 } ] } ] } ] } }, "multi_party_size": { "summary": "Multiple party sizes", "value": { "partner_business_id": "1071685", "service": "default", "dates": [ { "date": "2026-08-01", "party_sizes": [ { "party_size": 2, "openings": [ { "time": "18:00", "spots_open": 4 }, { "time": "18:30", "spots_open": 3 } ] }, { "party_size": 4, "openings": [ { "time": "18:00", "spots_open": 2 }, { "time": "19:00", "spots_open": 1 } ] } ] } ] } } } } } }, "responses": { "200": { "description": "Availability accepted (per-date results)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "results": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "accepted", "error" ] } } } } } } } }, "examples": { "success": { "value": { "success": true, "results": { "results": [ { "date": "2026-08-01", "status": "accepted" } ] } } } } } } }, "400": { "description": "Invalid request payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "examples": { "validation_error": { "value": { "success": false, "message": "partner_business_id and dates are required" } } } } } }, "401": { "description": "The API key has either expired or doesn't have the required scopes to query this endpoint.\n\n| code | description |\n| ------------- | ------------- |\n| UNAUTHORIZED_API_KEY | The API key provided is not currently able to query this endpoint. |\n| TOKEN_INVALID | Invalid API key or authorization header. |\n", "content": { "application/json": { "examples": { "Unauthorized": { "value": { "error": { "code": "UNAUTHORIZED_API_KEY", "description": "The API key provided is not currently able to query this endpoint." } } }, "Invalid Token": { "value": { "error": { "code": "TOKEN_INVALID", "description": "Invalid API key or authorization header." } } } }, "schema": { "$ref": "#/paths/~1v3~1bookings~1{business_id_or_alias}~1holds/post/responses/400/content/application~1json/schema" } } } }, "403": { "description": "Partner API endpoints require set up by Yelp before they can be used. You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1bookings~1{business_id_or_alias}~1holds/post/responses/400/content/application~1json/schema" }, "examples": { "Endpoint Disabled": { "value": { "error": { "code": "PARTNER_ENDPOINT_DISABLED", "description": "You are trying to access a Partner API endpoint for which your API Client has not been enabled. Please reach out to partner-support@yelp.com for more information." } } } } } } }, "404": { "description": "Partner business not found", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1private~1reservation_availability~1update/post/responses/400/content/application~1json/schema" }, "examples": { "not_found": { "value": { "success": false, "message": "Failed to process availability update" } } } } } }, "429": { "description": "You have either exceeded your daily quota, or have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "error": { "code": "TOO_MANY_REQUESTS_PER_SECOND", "description": "You have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries." } } } }, "schema": { "$ref": "#/paths/~1v3~1bookings~1{business_id_or_alias}~1holds/post/responses/400/content/application~1json/schema" } } } }, "500": { "description": "Failed to process availability update", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1private~1reservation_availability~1update/post/responses/400/content/application~1json/schema" }, "examples": { "upstream_error": { "value": { "success": false, "message": "Failed to process availability update" } } } } } }, "504": { "description": "Upstream timeout", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1private~1reservation_availability~1update/post/responses/400/content/application~1json/schema" }, "examples": { "upstream_timeout": { "value": { "success": false, "message": "Upstream timeout" } } } } } } } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": false, "samples-enabled": true }, "_id": { "buffer": { "0": 103, "1": 27, "2": 216, "3": 225, "4": 57, "5": 183, "6": 33, "7": 0, "8": 15, "9": 91, "10": 226, "11": 0 } } } ````