PropertyPlex Integration API

Getting Started

Base URL

https://your-server.com/api/v1/integration

All requests and responses use JSON. Include Content-Type: application/json in request headers.

Quick Start

1. Create an API key in System Admin → Integrations
2. Copy the key (shown once) — format: ppx_a1b2c3d4e5f6...
3. Include it in all requests via the X-API-Key header
4. Start with GET /properties/:propId/rooms to list rooms

Authentication

Authenticate every request by including your API key in the X-API-Key header:

# Preferred
curl -H "X-API-Key: ppx_your_api_key_here" \
  https://your-server.com/api/v1/integration/properties/:propId/rooms

# Alternative (Bearer token)
curl -H "Authorization: Bearer ppx_your_api_key_here" \
  https://your-server.com/api/v1/integration/properties/:propId/rooms

API Key Format

Keys start with ppx_ followed by 32 hexadecimal characters. They are shown once on creation — store them securely. Only the prefix is visible afterward.

Permissions

Each API key can be scoped to specific permissions. Include only the permissions your integration needs:

Property Scoping

API keys can optionally be scoped to specific properties. When scoped, requests to other properties return 403 Forbidden. Unscoped keys can access all properties in the tenant.

Rate Limits

Default: 100 requests per minute per API key (configurable per key in System Admin).

Rate limit info is returned in response headers:

When exceeded, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "retryAfter": 23
}

Rooms

Manage room status, guest information, and room inventory. Room status drives the housekeeping and front-desk workflow.

Room Statuses

{
  "count": 6,
  "rooms": [
    {
      "id": "uuid",
      "externalId": "102",
      "name": "Room 102",
      "roomNumber": "102",
      "roomType": "STANDARD",
      "floor": 1,
      "status": "OCCUPIED",
      "guestName": "James Wilson",
      "guestCheckoutDate": 1739836800000,
      "maxOccupancy": 2,
      "bedType": "KING",
      "bedCount": 1,
      "amenities": ["wifi", "minibar"],
      "description": "Garden view room",
      "locationName": "Floor 1",
      "openWorkOrders": 0,
      "sortOrder": 10,
      "createdAt": 1739000000000,
      "updatedAt": 1739500000000
    }
  ]
}

curl -H "X-API-Key: ppx_your_key" \
  https://your-server.com/api/v1/integration/properties/PROP_ID/rooms?status=TURNING

{
  "message": "Room sync complete",
  "created": 3,
  "updated": 2,
  "removed": 1,
  "unchanged": 0
}

curl -X POST -H "X-API-Key: ppx_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "rooms": [
      { "externalId": "101", "name": "Room 101", "roomNumber": "101", "roomType": "STANDARD", "floor": 1, "bedType": "KING", "bedCount": 1 },
      { "externalId": "102", "name": "Room 102", "roomNumber": "102", "roomType": "STANDARD", "floor": 1, "bedType": "QUEEN", "bedCount": 2 }
    ]
  }' \
  https://your-server.com/api/v1/integration/properties/PROP_ID/rooms/sync

{
  "id": "uuid",
  "externalId": "102",
  "name": "Room 102",
  "status": "INSPECTION",
  "guestName": null,
  "updatedAt": 1739500000000,
  "message": "Room redirected to INSPECTION (inspection required for this property)"
}

{
  "message": "Check-in successful",
  "roomId": "uuid",
  "externalId": "102",
  "status": "OCCUPIED",
  "guestName": "Jane Smith",
  "vipStatus": "VIP",
  "guestCount": { "adults": 2, "children": 1 }
}

{
  "message": "Check-out successful",
  "roomId": "uuid",
  "externalId": "102",
  "status": "TURNING"
}

Reservations

Push reservation data from your PMS to PropertyPlex. Reservations are displayed to housekeeping staff so they can see upcoming arrivals and special requests.

Reservation Statuses

{
  "message": "Reservation created",
  "id": "uuid",
  "externalId": "RES-12345"
}

{
  "count": 2,
  "reservations": [
    {
      "id": "uuid",
      "externalId": "RES-12345",
      "confirmationCode": "GH-7842",
      "guestName": "Emily Johnson",
      "guestEmail": "emily@example.com",
      "roomId": "uuid",
      "roomName": "Room 103",
      "roomNumber": "103",
      "checkInDate": 1739836800000,
      "checkOutDate": 1740096000000,
      "adultsCount": 2,
      "childrenCount": 0,
      "rateAmount": 189.00,
      "rateCurrency": "USD",
      "channel": "Booking.com",
      "specialRequests": "Late check-in, extra pillows",
      "vipStatus": null,
      "status": "CONFIRMED",
      "createdAt": 1739000000000,
      "updatedAt": 1739000000000
    }
  ]
}

{
  "message": "Reservation updated",
  "id": "uuid"
}

{
  "message": "Reservation deleted"
}

Work Orders

Create and manage maintenance work orders. Work orders created via the API are tagged with source: "INTEGRATION" and automatically assigned a sequential work order number.

Work Order Statuses

Priorities

{
  "message": "Work order created",
  "id": "uuid",
  "woNumber": 42,
  "status": "OPEN",
  "priority": "HIGH"
}

{
  "count": 1,
  "workOrders": [
    {
      "id": "uuid",
      "woNumber": 42,
      "title": "AC not cooling",
      "description": "Guest reports AC blowing warm air",
      "status": "OPEN",
      "priority": "HIGH",
      "issueType": "HVAC",
      "roomName": "Room 102",
      "roomNumber": "102",
      "roomExternalId": "102",
      "assignedToName": "John Doe",
      "createdAt": 1739000000000,
      "updatedAt": 1739000000000
    }
  ]
}

{
  "id": "uuid",
  "woNumber": 42,
  "status": "COMPLETED",
  "priority": "HIGH",
  "updatedAt": 1739500000000
}

Webhooks

Receive real-time notifications when events happen in PropertyPlex. Configure webhooks in System Admin → Integrations.

Events

Payload Structure

All webhook deliveries use POST with the following headers:

Request body:

{
  "event": "room.status_changed",
  "timestamp": 1739567890123,
  "data": {
    "roomId": "uuid",
    "externalId": "102",
    "oldStatus": "TURNING",
    "newStatus": "READY",
    "guestName": null
  }
}

Verifying Signatures

Always verify the X-PPX-Signature header to ensure the webhook is authentic. The signature is computed as sha256=HMAC-SHA256(raw_body, webhook_secret).

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBody);
  const expected = `sha256=${hmac.digest('hex')}`;
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-ppx-signature'];
  if (!verifyWebhook(JSON.stringify(req.body), sig, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.headers['x-ppx-event'];
  console.log(`Received: ${event}`, req.body.data);
  res.status(200).send('OK');
});

import hmac, hashlib

def verify_webhook(raw_body, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask example
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    sig = request.headers.get('X-PPX-Signature')
    if not verify_webhook(request.data.decode(), sig, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.headers.get('X-PPX-Event')
    data = request.json['data']
    print(f"Received: {event}", data)
    return 'OK', 200

PMS Connectors

PropertyPlex includes built-in connectors for popular Hotel Management Systems. Instead of building your own integration, you can connect directly from System Admin > Integrations.

View all connector setup guides →

Error Handling

All errors return a JSON object with an error field:

{
  "error": "Description of what went wrong"
}

HTTP Status Codes

Plan Upgrade Required

If your tenant is on the Starter plan, API requests return:

{
  "error": "Integration API requires Professional or Enterprise plan",
  "code": "PLAN_UPGRADE_REQUIRED"
}

Code Examples

Room Sync (Node.js)

const API_KEY = 'ppx_your_api_key';
const BASE = 'https://your-server.com/api/v1/integration';
const PROP_ID = 'your-property-uuid';

// Sync room inventory
const res = await fetch(`${BASE}/properties/${PROP_ID}/rooms/sync`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    rooms: [
      {
        externalId: '101',
        name: 'Room 101',
        roomNumber: '101',
        roomType: 'STANDARD',
        floor: 1,
        bedType: 'KING',
        bedCount: 1,
        maxOccupancy: 2,
        amenities: ['wifi', 'minibar', 'safe'],
      },
      {
        externalId: '102',
        name: 'Room 102',
        roomNumber: '102',
        roomType: 'STANDARD',
        floor: 1,
        bedType: 'QUEEN',
        bedCount: 2,
        maxOccupancy: 4,
      },
    ],
  }),
});

const data = await res.json();
console.log(data);
// { message: 'Room sync complete', created: 2, updated: 0, removed: 0 }

Check-in Flow (Python)

import requests

API_KEY = 'ppx_your_api_key'
BASE = 'https://your-server.com/api/v1/integration'
PROP_ID = 'your-property-uuid'

headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json',
}

# 1. Create reservation
res = requests.post(f'{BASE}/properties/{PROP_ID}/reservations', headers=headers, json={
    'externalId': 'RES-5001',
    'guestName': 'Alice Chen',
    'checkInDate': 1740000000000,
    'checkOutDate': 1740200000000,
    'roomId': 'room-uuid',
    'confirmationCode': 'CONF-1234',
    'specialRequests': 'Hypoallergenic pillows',
})
reservation_id = res.json()['id']

# 2. Check in (links reservation, imports special requests)
res = requests.post(f'{BASE}/properties/{PROP_ID}/rooms/room-uuid/check-in', headers=headers, json={
    'guestName': 'Alice Chen',
    'guestCheckoutDate': 1740200000000,
    'reservationId': reservation_id,
})
print(res.json())
# { message: 'Check-in successful', status: 'OCCUPIED', ... }

# 3. Check out (triggers housekeeping)
res = requests.post(f'{BASE}/properties/{PROP_ID}/rooms/room-uuid/check-out', headers=headers)
print(res.json())
# { message: 'Check-out successful', status: 'TURNING' }

Report Maintenance Issue (cURL)

curl -X POST \
  -H "X-API-Key: ppx_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AC not cooling in Room 102",
    "description": "Guest reports AC unit blowing warm air",
    "roomId": "room-uuid",
    "priority": "HIGH",
    "issueType": "HVAC"
  }' \
  https://your-server.com/api/v1/integration/properties/PROP_ID/work-orders