> ## 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.

# POST /guests/checkin

> Create a new in-house guest record when a guest checks in at your PMS.

## 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](/api/pms/testing#idempotency). |

## Request Body

```json theme={null}
{
  "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.        |

<Tip>
  **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.
</Tip>

## Response: Success (200)

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"
}
```

<Info>
  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.
</Info>

## Response: Duplicate Guest (409)

Returned when an active guest with the same `pmsGuestId` already exists:

```json theme={null}
{
  "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:

```json theme={null}
{
  "status": "error",
  "code": "FIELD_REQUIRED",
  "message": "lastName is required",
  "field": "lastName",
  "requestId": "req_a1b2c3d4"
}
```

See [Error Handling](/api/pms/errors) 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:

```json theme={null}
{
  "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

```bash theme={null}
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"
  }'
```