SidetalkGuides
Sidetalk website ↗Open dashboard

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/reservations

HTTP method

Plain Text
GET

Headers

HeadersValueDescription
AuthorizationBearer <api_key>Use the API KEY issued in Settings in the Sidetalk dashboard.

Parameters (query string)

ParameterTypeRequiredDescription
reservationsIdStringYesThe unique ID of the reservation form to query.
limitNumberNoReservations per page. Defaults to 50.
pageNumberNoThe 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

FieldTypeDescription
successBooleanWhether the request succeeded.
reservations_idStringThe unique ID of the queried reservation form.
reservations_nameStringThe reservation form name.
pageNumberThe current page number.
limitNumberItems per page.
total_countNumberThe total reservations registered in that form.
reservationsArrayThe retrieved reservations.

Reservation history (reservations)

FieldTypeDescription
reservation_idStringThe unique reservation record ID.
reservation_noStringThe booking number issued to the customer.
customer_nameStringThe customer’s name.
customer_phoneStringThe customer’s phone number.
customer_emailStringThe customer’s email.
party_sizeNumberParty size.
reservation_dateStringThe reservation date in YYYY-MM-DD format.
reservation_timeStringThe reservation time in HH:mm format.
statusStringThe reservation status.
sourceStringThe channel through which the reservation was registered.
custom_fieldsObjectCustom field values added to the reservation form.
created_atStringThe date and time the reservation was registered.
updated_atStringThe date and time the reservation was last modified.

Reservation status

StatusDescription
pendingBooking received or awaiting approval
confirmedBooking confirmed
cancelledBooking canceled
noshowMarked as no-show
completedBooking 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 codeDescription
200Reservation history retrieved successfully
400Invalid parameters or missing required values
403API KEY authentication failed
404Reservation form not found or inaccessible to the API KEY
500A 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.