M1 API Reference

The M1 Villa Management API provides endpoints for managing villas, owners, staff, documents, and onboarding workflows.

Base URL

Production: https://obv.inspiringlivingsolutions.com/api
Development: http://localhost:4002/api

Authentication

All endpoints require authentication via Clerk session.

Authorization: Bearer <clerk_session_token>

Endpoints

Villas

List Villas

GET /villas

Query Parameters:

Parameter	Type	Description
page	number	Page number
limit	number	Items per page
status	string	Filter by status
search	string	Search term

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "Villa Sunrise",
      "status": "ACTIVE",
      "propertyType": "VILLA",
      "bedrooms": 4,
      "location": "Koh Samui"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50
  }
}

Get Villa

GET /villas/:id

Create Villa

POST /villas

Body:

{
  "name": "Villa Name",
  "propertyType": "VILLA",
  "villaStyle": "MODERN",
  "bedrooms": 4,
  "bathrooms": 5,
  "maxGuests": 8
}

Update Villa

PATCH /villas/:id

Delete Villa

DELETE /villas/:id

---

Owners

List Owners

GET /owners

Get Owner

GET /owners/:id

Create Owner

POST /owners

Body (Individual):

{
  "ownerType": "INDIVIDUAL",
  "firstName": "John",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+66812345678"
}

Body (Company):

{
  "ownerType": "COMPANY",
  "companyName": "ABC Holdings",
  "registrationNumber": "123456789",
  "contactPerson": "Jane Doe",
  "email": "[email protected]"
}

---

Staff

List Staff

GET /staff

Get Staff

GET /staff/:id

Create Staff

POST /staff

Assign Staff to Villa

POST /villas/:villaId/staff

Body:

{
  "staffId": "uuid",
  "role": "HOUSEKEEPER",
  "isPrimary": true
}

---

Documents

List Villa Documents

GET /villas/:villaId/documents

Upload Document

POST /villas/:villaId/documents
Content-Type: multipart/form-data

Body:

• file: Document file
• documentType: Type of document
• title: Document title

Delete Document

DELETE /documents/:id

---

Photos

List Villa Photos

GET /villas/:villaId/photos

Upload Photos

POST /villas/:villaId/photos
Content-Type: multipart/form-data

Set Cover Photo

PATCH /photos/:id/cover

---

Onboarding

Get Onboarding Status

GET /villas/:villaId/onboarding

Response:

{
  "overallStatus": "IN_PROGRESS",
  "completionPercentage": 60,
  "steps": [
    {
      "step": "BASIC_INFO",
      "status": "COMPLETED"
    },
    {
      "step": "OWNER_DETAILS",
      "status": "IN_PROGRESS"
    }
  ]
}

Update Step Status

PATCH /villas/:villaId/onboarding/steps/:step

---

OTA Credentials

List OTA Credentials

GET /villas/:villaId/ota-credentials

Add OTA Credential

POST /villas/:villaId/ota-credentials

Body:

{
  "platform": "AIRBNB",
  "username": "[email protected]",
  "password": "encrypted_password",
  "propertyId": "12345"
}

---

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Not authenticated
FORBIDDEN	403	No permission
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid input
SERVER_ERROR	500	Internal error