Getting Started with InnKeeper API
Welcome to the InnKeeper API! This guide will help you integrate Oracle Hospitality Integration Platform (OHIP) systems with InnKeeper's task management and property management modules.
Overview
The InnKeeper API provides RESTful endpoints for:
- Task Management - Service requests, task assignments, and workflows
- Property Management - Housekeeping, maintenance, room status synchronization
- Oracle Webhooks - Real-time event notifications from Oracle PMS systems
Prerequisites
Before you begin, you'll need:
- InnKeeper Account - Contact sales@innkeeper.africa to create an account
- Entity ID - Your organization's unique identifier in InnKeeper
- API Credentials - Either:
- OAuth 2.0 client credentials (recommended for production)
- API key (for testing and simple integrations)
- Oracle OHIP Access (optional for webhook integration)
Quick Start (5 minutes)
Step 1: Get Your API Key
For testing, request a development API key from your account manager:
# Development API key example API_KEY=test-api-key-12345
Step 2: Test the API
Make your first request to verify connectivity:
# Check API health curl https://xyz.convex.site/api/v1/health
Expected response:
{
"success": true,
"data": {
"status": "healthy",
"version": "1.0.0",
"timestamp": "2026-02-16T10:30:00Z",
"service": "innkeeper-api"
}
}Step 3: Create a Service Request
curl -X POST https://xyz.convex.site/api/v1/task-manager/requests \
-H "Content-Type: application/json" \
-H "x-app-key: YOUR_API_KEY" \
-d '{
"title": "Extra towels needed",
"description": "Guest in room 305 requested extra towels",
"priority": "MEDIUM",
"room": "305",
"categoryId": "YOUR_CATEGORY_ID",
"entityId": "YOUR_ENTITY_ID"
}'Expected response:
{
"success": true,
"data": {
"requestId": "jr1mno345pqr678"
}
}Step 4: List All Requests
curl https://xyz.convex.site/api/v1/task-manager/requests?entityId=YOUR_ENTITY_ID \ -H "x-app-key: YOUR_API_KEY"
🎉 Congratulations! You've made your first API calls.
API Endpoints Overview
Task Manager
| Endpoint | Method | Description |
|---|---|---|
| /task-manager/requests | POST | Create service request |
| /task-manager/requests | GET | List all requests |
| /task-manager/requests/:id | GET | Get request details |
| /task-manager/requests/:id | PUT | Update request |
| /task-manager/requests/:id/assign | POST | Assign request to staff |
Property Management
| Endpoint | Method | Description |
|---|---|---|
| /property-management/housekeeping/reports | POST | Create housekeeping report |
| /property-management/housekeeping/reports | GET | List reports |
| /property-management/rooms | GET | List rooms |
| /property-management/rooms/:id | PUT | Update room status |
Rate Limits
| Tier | Requests per Minute |
|---|---|
| Standard | 100 |
| Premium | 1000 |
All responses include rate limit headers:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1640995200
Testing with Postman
We provide a complete Postman collection:
- Download the Postman Collection
- Import into Postman
- Update environment variables with your credentials
- Start testing!