Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.recepai.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

POST https://app.recepai.ai/api/pms/v1/{slug}/guests/checkin
Creates a new in-house guest record. The guest immediately becomes visible on the hotel’s Front Desk dashboard and available for AI-powered guest verification.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer pms_live_xxx or Bearer pms_test_xxx
Content-TypeYesapplication/json
Idempotency-KeyYesUnique key for this request (1–255 chars). See Idempotency.

​
Request Body

{
  "pmsGuestId": "RES-2026-001",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+905551234567",
  "roomNumber": "301",
  "checkInDate": "2026-02-18",
  "checkOutDate": "2026-02-22",
  "language": "en",
  "adults": 2,
  "children": 0,
  "nationality": "US",
  "email": "john.doe@gmail.com",
  "notes": "Late arrival, airport transfer arranged"
}

​
Field Reference

FieldTypeRequiredDescription
pmsGuestIdstringYesYour PMS’s own reservation or guest identifier. Must be unique among active guests. Max 255 chars.
lastNamestringYesGuest last name. Max 100 chars.
roomNumberstringYesRoom number. Must match a room in the hotel’s configured room list.
checkOutDatestringYesExpected checkout date in YYYY-MM-DD format. Must be on or after checkInDate.
firstNamestringNoGuest first name. Max 100 chars.
phonestringNoPhone in E.164 format: + followed by country code and number, no spaces or dashes. Example: +905551234567.
checkInDatestringNoCheck-in date in YYYY-MM-DD format. Defaults to today if omitted.
languagestringNoISO 639-1 language code (en, tr, de, fr, es, ru, etc.). Defaults to en.
adultsintegerNoNumber of adults (1–20). Defaults to 1.
childrenintegerNoNumber of children (0–20). Defaults to 0.
nationalitystringNoISO 3166-1 alpha-2 country code (US, TR, DE, etc.).
emailstringNoGuest email address.
notesstringNoFree-text notes about the guest (max 2000 chars). Saved as a staff note visible on the guest’s profile.
Include the phone number whenever possible. The AI receptionist uses the phone number to verify guest identity when handling service requests. Without it, the AI cannot confirm who is calling or messaging.

​
Response: Success (200)

{
  "status": "created",
  "guestId": "abc123-def456",
  "pmsGuestId": "RES-2026-001",
  "roomNumber": "301",
  "requestId": "req_a1b2c3d4"
}
FieldDescription
statusAlways "created" on success
guestIdRecepAI’s internal ID for this guest record
pmsGuestIdEcho of your PMS guest identifier
roomNumberEcho of the assigned room
requestIdUnique ID for this request (use for support inquiries)

​
Response: Room Occupied (409)

Returned when the specified room already has an active guest: 
{
  "status": "error",
  "code": "ROOM_OCCUPIED",
  "message": "Room 301 is already occupied by an active guest",
  "currentGuest": {
    "pmsGuestId": "RES-2026-000",
    "lastName": "Smith",
    "checkInDate": "2026-02-15"
  },
  "requestId": "req_a1b2c3d4"
}
The currentGuest object helps you identify who is currently in the room, so you can resolve the conflict — either check out the previous guest first, or correct the room number.

​
Response: Duplicate Guest (409)

Returned when an active guest with the same pmsGuestId already exists: 
{
  "status": "error",
  "code": "DUPLICATE_GUEST",
  "message": "Active guest with pmsGuestId RES-2026-001 already exists",
  "existingGuest": {
    "guestId": "abc123-def456",
    "roomNumber": "301"
  },
  "requestId": "req_a1b2c3d4"
}

​
Response: Validation Error (400)

Returned when required fields are missing or field values are invalid: 
{
  "status": "error",
  "code": "FIELD_REQUIRED",
  "message": "lastName is required",
  "field": "lastName",
  "requestId": "req_a1b2c3d4"
}
See Error Handling for the complete list of validation rules and error codes.

​
Idempotency

If you send the same Idempotency-Key within 24 hours, the original response is returned without creating a duplicate guest: 
{
  "status": "created",
  "guestId": "abc123-def456",
  "pmsGuestId": "RES-2026-001",
  "roomNumber": "301",
  "requestId": "req_a1b2c3d4",
  "_idempotent": true
}
The _idempotent: true flag tells you this is a cached response from a previous identical request.

​
Example: Full cURL

curl -X POST https://app.recepai.ai/api/pms/v1/grand-hotel/guests/checkin \
  -H "Authorization: Bearer pms_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkin_RES2026001_20260218" \
  -d '{
    "pmsGuestId": "RES-2026-001",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+905551234567",
    "roomNumber": "301",
    "checkInDate": "2026-02-18",
    "checkOutDate": "2026-02-22",
    "language": "en",
    "adults": 2,
    "children": 0,
    "nationality": "US",
    "email": "john.doe@gmail.com"
  }'