Skip to main content
This guide walks you through your first API calls — from verifying your credentials to checking in and checking out a test guest.

​
Prerequisites

Before you start, make sure you have:
  • An API key (either pms_live_ or pms_test_ prefix)
  • The hotel slug (e.g., grand-hotel)
Both are provided by the hotel administrator. See Authentication for details.
Use a test key first. If you have a pms_test_ key, use it for this tutorial. Test keys validate your payloads but don’t write any data to the hotel’s system. You can switch to the live key when you’re ready for production.

​
Step 1: Verify Your Credentials

Start by listing current guests. This confirms your API key and slug are working: 
curl -X GET https://app.recepai.ai/api/pms/v1/grand-hotel/guests \
  -H "Authorization: Bearer pms_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
Expected response (200 OK): 
{
  "guests": [],
  "count": 0,
  "requestId": "req_a1b2c3d4"
}
If you get a 401 error, double-check your API key and slug. See Authentication Errors.

​
Step 2: Check In a Guest

Send a check-in event with the required fields: 
curl -X POST https://app.recepai.ai/api/pms/v1/grand-hotel/guests/checkin \
  -H "Authorization: Bearer pms_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test_checkin_001" \
  -d '{
    "pmsGuestId": "TEST-001",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+905551234567",
    "roomNumber": "301",
    "checkInDate": "2026-02-18",
    "checkOutDate": "2026-02-22",
    "language": "en"
  }'
Expected response (200 OK): 
{
  "status": "created",
  "guestId": "test_abc123",
  "pmsGuestId": "TEST-001",
  "roomNumber": "301",
  "requestId": "req_test_b2c3d4",
  "_sandbox": true
}
The _sandbox: true flag appears only with test keys. It confirms that no real data was written. With a live key, this flag won’t be present and the guest will appear on the hotel’s dashboard immediately.

​
Step 3: Verify the Guest

List guests again to confirm the check-in was recorded: 
curl -X GET https://app.recepai.ai/api/pms/v1/grand-hotel/guests \
  -H "Authorization: Bearer pms_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
With a test key, the list will still be empty (test mode doesn’t write data). With a live key, you’d see your guest in the response.

​
Step 4: Check Out the Guest

When the guest departs, send a checkout event: 
curl -X POST https://app.recepai.ai/api/pms/v1/grand-hotel/guests/checkout \
  -H "Authorization: Bearer pms_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test_checkout_001" \
  -d '{
    "pmsGuestId": "TEST-001"
  }'
Expected response (200 OK): 
{
  "status": "checked_out",
  "guestId": "test_abc123",
  "pmsGuestId": "TEST-001",
  "roomNumber": "301",
  "requestId": "req_test_c3d4e5",
  "_sandbox": true
}

​
What’s Next?

You’ve completed the basic flow. Here’s where to go from here:

Check In

Full field reference for guest check-in — all 12 fields, validation rules, error responses.

Full Sync

Nightly reconciliation — send your complete guest list and RecepAI handles the rest.

Error Handling

All error codes, validation rules, and common mistakes.

Testing

Sandbox mode, idempotency keys, and rate limits.