--- agentTools: projectIndex: https://docs.developer.yelp.com/llms.txt --- # Join queue Join the queue for a restaurant. **Note:** Prior to making a call to this endpoint, the restaurant must currently be on a wait, nor the API caller will receive response with 422 `CURRENTLY_NO_WAIT`. Enqueuing the first party on the waitlist can be achieved by using the Yelp Guest Manager app. **Curl example with OAuth authentication:** ```sh root@test:~# curl -X POST https://api.yelp.com/v3/businesses/{BUSINESS_ID}/waitlist/visits --header 'accept: application/json' --header "Authorization: Bearer ${API_TOKEN}" -d "{\"name\": \"Customer Name\", \"party_size\": 2, \"phone\": \"+19050000000\"}" ``` **Example 200 response:** ```json { "visit_id": "Encoded visit id", "queue_time": 1714576951, "party_size": 2, "arrive_by_time": 1714577011, "expected_seating_time_min": 1714577011, "expected_seating_time_max": 1714577551, "seating_area_preference": "" } ``` **Note 2:** In order to use this endpoint, the caller should be an onboarded Yelp Waitlist partner. # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "Waitlist Partner 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/partner/restaurants": { "get": { "summary": "Partner Restaurants", "tags": [ "Waitlist" ], "description": "This endpoint returns a list of restaurants that were onboarded with the partner. Both Business ID and Display name will be returned for each onboarded restaurants.\n\n**Curl example with OAuth authentication:**\n```sh\n root@test:~# curl -X GET \"https://api.yelp.com/v3/partner/restaurants\" --header \"Authorization: Bearer ${API_TOKEN}\" --header \"Content-Type: application/json\"\n```\n\n**Example 200 response:**\n```json\n{\n \"restaurants\": [\n {\n \"business_id\": \"Yelp business id 1\",\n \"display_name\": \"Partner onboarded business 1\"\n },\n {\n \"business_id\": \"Yelp business id 2\",\n \"display_name\": \"Partner onboarded business 2\"\n }\n ]\n}\n```\n\n**Note:** In order to use this endpoint, the caller should be an onboarded Yelp Waitlist partner\n", "operationId": "v3_partner_restaurants", "responses": { "200": { "description": "An object contains a list of onboarded restaurants of the calling partner returned.", "content": { "application/json": { "schema": { "type": "object", "description": "The object containing a list of restaurants that was onboared to the partner", "properties": { "restaurants": { "type": "array", "items": { "type": "object", "properties": { "business_id": { "description": "Yelp encrypted business identifier", "type": "string", "example": "jWyUGZyE4mfy7fK8GE-I4w" }, "display_name": { "description": "Business name for displaying purpose", "type": "string", "example": "Wonderful restaurant" } }, "required": [ "business_id", "display_name" ] } } } }, "examples": { "Result": { "value": { "restaurants": [ { "display_name": "fantastic-restaurant-1", "business_id": "jWyUGZyE4mfy7fK8GE-I4w" }, { "display_name": "wonderful-restaurant-1", "business_id": "88H67LQktcGY_Hlk_GXXmQ" } ] } } } } } }, "400": { "description": "Bad Request. Message varies depending on failure scenario", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1visits~1{visit_id}~1cancel/post/responses/409/content/application~1json/schema" }, "examples": { "Invalid Request": { "value": { "error": { "code": "INVALID_REQUEST", "description": "Invalid Request" } } } } } } }, "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~1visits~1{visit_id}~1cancel/post/responses/409/content/application~1json/schema" } } } }, "404": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1visits~1{visit_id}~1cancel/post/responses/409/content/application~1json/schema" }, "examples": { "Resource Not Found": { "value": { "error": { "code": "NOT_FOUND", "description": "Resource Not Found" } } } } } } }, "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~1visits~1{visit_id}~1cancel/post/responses/409/content/application~1json/schema" } } } }, "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~1visits~1{visit_id}~1cancel/post/responses/409/content/application~1json/schema" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1visits~1{visit_id}~1cancel/post/responses/409/content/application~1json/schema" }, "examples": { "Service Unavailable": { "value": { "error": { "code": "SERVICE_UNAVAILABLE", "description": "Service Unavailable" } } } } } } } } } }, "/v3/businesses/{business_id}/waitlist/visits": { "post": { "summary": "Join queue", "tags": [ "Waitlist" ], "description": "Join the queue for a restaurant.\n\n**Note:** Prior to making a call to this endpoint, the restaurant must currently be on a wait, nor the API caller will receive response with 422 `CURRENTLY_NO_WAIT`. Enqueuing the first party on the waitlist can be achieved by using the Yelp Guest Manager app.\n\n**Curl example with OAuth authentication:**\n```sh\n root@test:~# curl -X POST https://api.yelp.com/v3/businesses/{BUSINESS_ID}/waitlist/visits --header 'accept: application/json' --header \"Authorization: Bearer ${API_TOKEN}\" -d \"{\\\"name\\\": \\\"Customer Name\\\", \\\"party_size\\\": 2, \\\"phone\\\": \\\"+19050000000\\\"}\"\n```\n\n**Example 200 response:**\n```json\n{\n \"visit_id\": \"Encoded visit id\",\n \"queue_time\": 1714576951,\n \"party_size\": 2,\n \"arrive_by_time\": 1714577011,\n \"expected_seating_time_min\": 1714577011,\n \"expected_seating_time_max\": 1714577551,\n \"seating_area_preference\": \"\"\n}\n```\n\n**Note 2:** In order to use this endpoint, the caller should be an onboarded Yelp Waitlist partner.\n", "operationId": "v3_business_waitlist_visits", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Encrypted Yelp business identifer", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The request object for joining the queue of the restaurant", "properties": { "phone": { "description": "Patron's phone number in E.164 format", "type": "string", "example": "+15300001111" }, "party_size": { "description": "Number of guests in the party", "type": "integer", "example": 4 }, "name": { "description": "Patron's name", "type": "string", "example": "Max" }, "seating_area_preference": { "description": "Preferred seating area of the visit.\n", "type": "string", "example": "FIRST", "x-nullable": true }, "party_notes": { "description": "Notes from the patron. Will be visible to the host in the host app.", "type": "string", "example": "notes", "x-nullable": true }, "idempotency_token": { "description": "Idempotency token to uniquely identify request", "type": "string", "example": "ea3cc669-e74d-4ef3-bc78-f85d86ea1549", "x-nullable": true } }, "required": [ "phone", "party_size", "name" ] } } } }, "responses": { "201": { "description": "An object contains information about the created waitlist visit", "content": { "application/json": { "schema": { "type": "object", "description": "The response object contains visit information of the created waitlist visit", "properties": { "visit_id": { "description": "Encrypted visit identifier", "type": "string", "example": "eHlbyNqumczMVTttlLq_qw" }, "queue_time": { "description": "Unix timestamp (seconds) when the visit was enqueued", "type": "integer", "example": 1425399061 }, "party_size": { "description": "The number of guests in the visit", "type": "integer", "example": 4 }, "arrive_by_time": { "description": "Unix timestamp (seconds) when guest should be told to arrive at restaurant", "type": "integer", "example": 1571950722 }, "expected_seating_time_min": { "description": "Unix timestamp (seconds) lower bound of estimated seating time", "type": "integer", "example": 1571950722 }, "expected_seating_time_max": { "description": "Unix timestamp (seconds) upper bound of estimated seating time", "type": "integer", "example": 1571952522 }, "seating_area_preference": { "description": "The seating area preference indicated by the guest", "type": "string", "example": "FIRST" } }, "required": [ "visit_id", "queue_time", "party_size", "arrive_by_time", "expected_seating_time_min", "expected_seating_time_max", "seating_area_preference" ] }, "examples": { "Result": { "value": { "visit_id": "eHlbyNqumczMVTttlLq_qw", "queue_time": 1425399061, "party_size": 4, "quoted_wait": 20, "min_quoted_wait": 5, "arrive_by_time": 1571950722, "expected_seating_time_min": 1571950722, "expected_seating_time_max": 1571952522, "seating_area_preference": "FIRST" } } } } } }, "400": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/400" }, "401": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/401" }, "404": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/404" }, "422": { "description": "This error is returned in any of the following scenarios:\n\n| Status |\terror_code | Reason\n| ------- | ----------------------- | ------------------------------\n| 422 | INVALID_SEATING_PREFERENCE | Invalid seating area preference or seating area preference is not supported by the restaurant\n| 422 | ALREADY_IN_LINE | Invalid state. eg. Phone number is already in line\n| 422 | CURRENTLY_NO_WAIT | Join-queue is ineligible, there is currently no wait for the restaurant\n| 422 | PARTY_SIZE_TOO_LARGE | Party size too large\n| 422 | RESTAURANT_NOT_OPEN | Restaurant is not open\n| 422 | REMOTE_ENTRY_DENIED | Restaurant does not allow remote entry\n| 422 | SCHEDULE_CONFLICT | Special event at restaurant\n", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1visits~1{visit_id}~1cancel/post/responses/409/content/application~1json/schema" } } } }, "429": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/429" }, "500": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/500" }, "503": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/503" } } } }, "/v3/visits/{visit_id}/cancel": { "post": { "summary": "Cancel a visit", "tags": [ "Waitlist" ], "description": "Cancel an on-my-way or a waitlist visit by the given encrypted visit identifier.\n\n**Curl example with OAuth authentication:**\n```sh\n root@test:~# curl -X POST \"https://api.yelp.com/v3/visits/{VISIT_ID}/cancel\" --header 'accept: application/json' --header \"Authorization: Bearer ${API_TOKEN}\"\n```\n\nIf the visit is canceled successfully, the client will receive an empty 204 response.\n\n**Note:** In order to use this endpoint, the caller should be an onboarded Yelp Waitlist partner\n", "operationId": "v3_visit_cancel", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "Encrypted Yelp visit identifer", "schema": { "type": "string" } } ], "responses": { "204": { "description": "The visit is canceled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/400" }, "401": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/401" }, "404": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/404" }, "409": { "description": "This error is returned in any of the following scenarios:\n\n| Status |\terror_code | Reason\n| ------- | ----------------------- | ------------------------------\n| 409 | VISIT_ALREADY_IN_TERMINAL_STATE | This visit was already in a terminal state or the customer is not in queue\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." } } } } } } } }, "429": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/429" }, "500": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/500" }, "503": { "$ref": "#/paths/~1v3~1partner~1restaurants/get/responses/503" } } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": false, "samples-enabled": true }, "_id": { "buffer": { "0": 100, "1": 220, "2": 158, "3": 146, "4": 90, "5": 144, "6": 255, "7": 0, "8": 37, "9": 233, "10": 246, "11": 172 } } } ````