POST /guests/checkin

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

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 (e.g., `"301"`, `"P2-105"`).
`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",
  "guestId": "abc123-def456",
  "roomNumber": "301",
  "requestId": "req_a1b2c3d4"
}

Field	Description
`guestId`	RecepAI’s internal ID for the existing guest record
`roomNumber`	The room where the existing guest is currently checked in

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"
  }'

Getting Started

Endpoints

Reference

POST /guests/checkin

Endpoint

Headers

Request Body

Field Reference

Response: Success (200)

Response: Room Occupied (409)

Response: Duplicate Guest (409)

Response: Validation Error (400)

Idempotency

Example: Full cURL

​Endpoint

​Headers

​Request Body

​Field Reference

​Response: Success (200)

​Response: Room Occupied (409)

​Response: Duplicate Guest (409)

​Response: Validation Error (400)

​Idempotency

​Example: Full cURL

Endpoint

Headers

Request Body

Field Reference

Response: Success (200)

Response: Room Occupied (409)

Response: Duplicate Guest (409)

Response: Validation Error (400)

Idempotency

Example: Full cURL