🏨 Check-In Provider Flow

The Check-In Provider Flow allows external systems to connect with Octorate in order to:

• Receive real-time notifications of new or updated reservations

• Access guest and booking details necessary for digital check-in

• Report check-in operations back to Octorate (manual or automatic)

• Keep Octorate’s internal status synchronized with external providers

This flow is typically used by:

• 🔐 Smart lock systems (for digital key management)

• 🧾 Guest registration platforms (for ID verification or police report)

• 🧳 Self check-in kiosks or mobile apps

🧭 Flow Overview

Step	Action	Endpoint	Description
1	Receive new reservation notification	/rest/v1/webhook	Webhook event: new or updated reservation
2	Retrieve reservation details	/rest/v1/reservation/{accommodation}/{reservationId}	Get full guest and stay information
3	Perform guest check-in	/rest/v1/checkin/{accommodation}	Register guest arrival
4	Update check-in information	/rest/v1/checkin/{accommodation}/{checkinId}	Update notes, time, or status
5	Retrieve check-in list	/rest/v1/checkin/{accommodation}	Get all check-ins for the property

---

📩 Step 1 — Receive Reservation Notifications

Check-In Providers typically use webhooks to get real-time updates from Octorate. When a new reservation is created or modified, Octorate sends an event to your webhook URL.

Webhook Registration

POST /rest/v1/webhook

Example Request

{
  "url": "https://your-provider.com/webhooks/octorate",
  "events": [
    "RESERVATION_CREATED",
    "RESERVATION_UPDATED",
    "CHECKIN_PERFORMED",
    "CHECKOUT_PERFORMED"
  ]
}

Example Webhook Payload

{
  "type": "RESERVATION_CREATED",
  "content": {
    "id": 880115,
    "refer": "RES-24001",
    "checkin": "2024-12-20T23:00:00Z[UTC]",
    "checkout": "2024-12-27T04:00:00Z[UTC]",
    "guests": [
      {
        "givenName": "Carlo",
        "familyName": "Verdi",
        "email": "[e-mail]",
        "phone": "[phone]",
        "type": "BOOKER"
      }
    ],
    "accommodation": {
      "id": "300001"
    }
  },
  "reference": "880115",
  "retry": 0
}

✅ Use case: Your system automatically detects the new reservation and prepares a digital check-in or door code.

---

🧾 Step 2 — Retrieve Reservation & Guest Details

To retrieve the complete reservation with all guest data, call:

GET /rest/v1/reservation/{accommodation}/{reservationId}

Example Response

{
  "id": 880115,
  "reservationCode": "RES-24001",
  "arrivalDate": "2025-12-20",
  "departureDate": "2025-12-27",
  "status": "CONFIRMED",
  "guest": {
    "id": 10567,
    "firstName": "Carlo",
    "lastName": "Verdi",
    "email": "[e-mail]",
    "phone": "[phone]",
    "country": "IT"
  },
  "rooms": [
    {
      "roomId": 554504,
      "adults": 2,
      "children": 0
    }
  ]
}

✅ This provides all the information your system needs to prepare a digital key or registration form.

---

🏨 Step 3 — Perform the Check-In

Once the guest arrives or your system performs an automatic check-in, you can notify Octorate via:

POST /rest/v1/checkin/{accommodation}

Example Request

{
  "reservationId": 880115,
  "guestId": 10567,
  "checkinDate": "2025-12-20T14:30:00Z",
  "notes": "Digital self check-in completed successfully"
}

Example Response

{
  "id": 5001,
  "reservationId": 880115,
  "guestId": 10567,
  "checkinDate": "2025-12-20T14:30:00Z",
  "status": "CHECKED_IN"
}

✅ Octorate automatically updates the reservation status and triggers the CHECKIN_PERFORMED webhook event.

---

✏️ Step 4 — Update an Existing Check-In

If you need to modify check-in details (e.g., correct time, add notes):

PUT /rest/v1/checkin/{accommodation}/{checkinId}

Example Request

{
  "checkinDate": "2025-12-20T15:00:00Z",
  "notes": "Guest arrived later than expected"
}

Example Response

{
  "id": 5001,
  "reservationId": 880115,
  "guestId": 10567,
  "checkinDate": "2025-12-20T15:00:00Z",
  "status": "CHECKED_IN"
}

---

📋 Step 5 — Retrieve All Check-Ins

✅ Useful for synchronizing the list of arrivals for a given day.

GET /rest/v1/checkin/{accommodation}

Example Response

[
  {
    "id": 5001,
    "reservationId": 880115,
    "guestName": "Carlo Verdi",
    "checkinDate": "2025-12-20T14:30:00Z",
    "status": "CHECKED_IN"
  },
  {
    "id": 5002,
    "reservationId": 880116,
    "guestName": "Anna Rossi",
    "checkinDate": "2025-12-22T13:00:00Z",
    "status": "CHECKED_IN"
  }
]

---

⚠️ Common Errors

HTTP Code	Error	Description
400	ApiParamsExemption	Missing required parameters (e.g., reservationId)
401	ApiKeyInvalid	Missing or invalid OAuth token
403	ApiSecurityException	No access to this accommodation
404	ApiResourceMissing	Reservation or check-in not found
500	InternalServerError	Unexpected issue from Octorate

---

💡 Best Practices

✅ Register RESERVATION_CREATED and CHECKIN_PERFORMED webhooks for automation. ✅ Always check the accommodationId in webhook payloads before processing. ✅ Handle retries — Octorate resends webhooks if your system doesn’t return 200 OK. ✅ Use ISO 8601 date format (YYYY-MM-DDTHH:mm:ssZ) for all timestamps. ✅ Log all webhook deliveries and API responses for traceability. ✅ If you integrate with digital keys, ensure synchronization occurs after Octorate confirms the reservation status.

---

🧭 Complete Check-In Provider Flow Summary

Step	Action	Endpoint / Trigger	Description
1	Receive reservation	Webhook: RESERVATION_CREATED	Triggered automatically by Octorate
2	Retrieve details	GET /reservation/{accommodation}/{id}	Get guest info
3	Perform check-in	POST /checkin/{accommodation}	Register arrival
4	Update check-in	PATCH /checkin/{accommodation}/{checkinId}	Edit info if needed
5	Sync back	Webhook: CHECKIN_PERFORMED	Confirmation from Octorate
6	Retrieve check-ins	GET /checkin/{accommodation}	For dashboards or reports

---

✅ Outcome

The Check-In Provider Flow ensures that external systems — such as digital key providers, guest registration tools, or kiosks — remain fully synchronized with Octorate in real time, with a two-way data exchange covering reservations, guests, and arrivals.