Reservation History Query API
Purpose
This API retrieves reservations registered in a specific reservation form in newest-first order by registration date.
Use limit and page to retrieve reservation history in pages.
URL
Plain Text
https://api.sidetalk.ai/v1/reservationsHTTP method
Plain Text
GETHeaders
| Headers | Value | Description |
|---|---|---|
| Authorization | Bearer <api_key> | Use the API KEY issued in Settings in the Sidetalk dashboard. |
Parameters (query string)
| Parameter | Type | Required | Description |
|---|---|---|---|
| reservationsId | String | Yes | The unique ID of the reservation form to query. |
| limit | Number | No | Reservations per page. Defaults to 50. |
| page | Number | No | The page number. Defaults to 1. |
Example request
Retrieve the latest 10 reservations
Shell
curl -X GET \
"https://api.sidetalk.ai/v1/reservations?reservationsId=${RESERVATIONS_ID}&limit=10&page=1" \
-H "Authorization: Bearer ${API_KEY}"Retrieve the second page
Shell
curl -X GET \
"https://api.sidetalk.ai/v1/reservations?reservationsId=${RESERVATIONS_ID}&limit=10&page=2" \
-H "Authorization: Bearer ${API_KEY}"Retrieve with defaults
If limit and page are omitted, retrieves 20 reservations from the first page.
Shell
curl -X GET \
"https://api.sidetalk.ai/v1/reservations?reservationsId=${RESERVATIONS_ID}" \
-H "Authorization: Bearer ${API_KEY}"Response format
The response is JSON.
Reservations are returned in newest-first order by created_at.
Response body
JavaScript
{
"success": true,
"reservations_id": "019e48dc-4f3f-7c9f-9d4f-9b4aa42c2caa",
"reservations_name": "상담 예약",
"page": 1,
"limit": 10,
"total_count": 25,
"reservations": [
{
"reservation_id": "019e48dc-8a20-72e1-9ab3-0ed7bb45f821",
"reservation_no": "R202607300001",
"customer_name": "홍길동",
"customer_phone": "010-1234-5678",
"customer_email": "user@example.com",
"party_size": 2,
"reservation_date": "2026-08-01",
"reservation_time": "14:30",
"request_note": "창가 자리",
"status": "confirmed",
"created_at": "2026-07-30T03:00:00.000Z",
"updated_at": "2026-07-30T03:10:00.000Z"
}
]
}Response fields
Query result
| Field | Type | Description |
|---|---|---|
| success | Boolean | Whether the request succeeded. |
| reservations_id | String | The unique ID of the queried reservation form. |
| reservations_name | String | The reservation form name. |
| page | Number | The current page number. |
| limit | Number | Items per page. |
| total_count | Number | The total reservations registered in that form. |
| reservations | Array | The retrieved reservations. |
Reservation history (reservations)
| Field | Type | Description |
|---|---|---|
| reservation_id | String | The unique reservation record ID. |
| reservation_no | String | The booking number issued to the customer. |
| customer_name | String | The customer’s name. |
| customer_phone | String | The customer’s phone number. |
| customer_email | String | The customer’s email. |
| party_size | Number | Party size. |
| reservation_date | String | The reservation date in YYYY-MM-DD format. |
| reservation_time | String | The reservation time in HH:mm format. |
| status | String | The reservation status. |
| source | String | The channel through which the reservation was registered. |
| custom_fields | Object | Custom field values added to the reservation form. |
| created_at | String | The date and time the reservation was registered. |
| updated_at | String | The date and time the reservation was last modified. |
Reservation status
| Status | Description |
|---|---|
| pending | Booking received or awaiting approval |
| confirmed | Booking confirmed |
| cancelled | Booking canceled |
| noshow | Marked as no-show |
| completed | Booking completed |
Example code (JavaScript)
JavaScript
async function getReservations(
reservationsId,
limit = 20,
page = 1
) {
const baseUrl = "https://api.sidetalk.ai/v1/reservations";
const params = new URLSearchParams({
reservationsId,
limit: String(limit),
page: String(page)
});
try {
const response = await fetch(
`${baseUrl}?${params.toString()}`,
{
method: "GET",
headers: {
Authorization: "Bearer [API_KEY]"
}
}
);
const result = await response.json();
if (!response.ok || !result.success) {
console.error(
"Server Error:",
result.error || "Unknown error"
);
return;
}
console.log(`현재 페이지: ${result.page}`);
console.log(`전체 예약 수: ${result.total_count}`);
result.reservations.forEach((reservation) => {
console.log(
`[${reservation.created_at}]`,
reservation.reservation_no,
reservation.customer_name,
reservation.reservation_date,
reservation.reservation_time
);
});
return result;
} catch (error) {
console.error("Error fetching reservations:", error);
}
}Retrieve the latest 10 reservations:
JavaScript
getReservations("RESERVATIONS_ID", 10, 1);Retrieve the second page:
JavaScript
getReservations("RESERVATIONS_ID", 10, 2);Error response
If a processing error occurs, the following response is returned.
Plain Text
{
"success": false,
"error": "Reservation form not found."
}HTTP status code
| Status code | Description |
|---|---|
| 200 | Reservation history retrieved successfully |
| 400 | Invalid parameters or missing required values |
| 403 | API KEY authentication failed |
| 404 | Reservation form not found or inaccessible to the API KEY |
| 500 | A server error occurred while retrieving reservations |
Cautions
- reservationsId is required.
- reservationsId must be a UUID.
- page defaults to 1 and must be an integer of at least 1.
- Reservations are returned in newest-first order by their creation date, created_at.
- Only reservation forms owned by the API KEY’s site can be queried.
- Requesting reservationsId from another site returns a 404 error.
- Responses may contain personal information such as customer names, phone numbers, and email addresses.
- To protect the API KEY, call this API from your server rather than the browser.
- Do not expose the API KEY in frontend code or a public repository.
