Endpoint
POST https://app.recepai.ai/api/pms/v1/{slug}/guests/checkin
| Header | Required | Description |
|---|
Authorization | Yes | Bearer pms_live_xxx or Bearer pms_test_xxx |
Content-Type | Yes | application/json |
Idempotency-Key | Yes | Unique 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
| Field | Type | Required | Description |
|---|
pmsGuestId | string | Yes | Your PMS’s own reservation or guest identifier. Must be unique among active guests. Max 255 chars. |
lastName | string | Yes | Guest last name. Max 100 chars. |
roomNumber | string | Yes | Room number. Must match a room in the hotel’s configured room list. |
checkOutDate | string | Yes | Expected checkout date in YYYY-MM-DD format. Must be on or after checkInDate. |
firstName | string | No | Guest first name. Max 100 chars. |
phone | string | No | Phone in E.164 format: + followed by country code and number, no spaces or dashes. Example: +905551234567. |
checkInDate | string | No | Check-in date in YYYY-MM-DD format. Defaults to today if omitted. |
language | string | No | ISO 639-1 language code (en, tr, de, fr, es, ru, etc.). Defaults to en. |
adults | integer | No | Number of adults (1–20). Defaults to 1. |
children | integer | No | Number of children (0–20). Defaults to 0. |
nationality | string | No | ISO 3166-1 alpha-2 country code (US, TR, DE, etc.). |
email | string | No | Guest email address. |
notes | string | No | Free-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"
}
| Field | Description |
|---|
status | Always "created" on success |
guestId | RecepAI’s internal ID for this guest record |
pmsGuestId | Echo of your PMS guest identifier |
roomNumber | Echo of the assigned room |
requestId | Unique 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"
}
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
}
_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"
}'
