API

Organizations - Base

Retrieve organization details and public organization lookup.

Base path: /api/v1/organizations and /api/v1/tenant

Organization endpoints provide read access to organization details. For management (branches, packages, hours), see Organizations submodules.

GET `/api/v1/organizations` — Get Organization

Auth: Protected (Authorization: Bearer <accessToken>)
Used by: owner-booki-web-app · Role: owner, branch-manager
Description: Get the authenticated user's organization details.

Request

GET /api/v1/organizations

Response (200 OK)

{
  "_id": "69dcbeec1a79a4eac35bc721",
  "name": "Jane's Beauty Salon",
  "businessPermit": "BP-2024-001",
  "businessRegistration": "BR-2024-001",
  "branch": 1,
  "slug": "janes-salon",
  "businessAddress": {
    "region": "NCR",
    "province": "Metro Manila",
    "municipalOrCity": "Quezon City",
    "barangay": "Doña Julia",
    "zip": "1100",
    "street": "Main Avenue",
    "address": "123 Business Complex"
  },
  "mayaConnected": true,
  "cashConnected": false,
  "businessHoursSettings": {
    "businessHours": [
      {
        "day": "monday",
        "isOpen": true,
        "openTime": "08:00",
        "closeTime": "17:00"
      },
      {
        "day": "tuesday",
        "isOpen": true,
        "openTime": "08:00",
        "closeTime": "17:00"
      },
      {
        "day": "wednesday",
        "isOpen": true,
        "openTime": "08:00",
        "closeTime": "17:00"
      },
      {
        "day": "thursday",
        "isOpen": true,
        "openTime": "08:00",
        "closeTime": "17:00"
      },
      {
        "day": "friday",
        "isOpen": true,
        "openTime": "08:00",
        "closeTime": "17:00"
      },
      {
        "day": "saturday",
        "isOpen": false,
        "openTime": "08:00",
        "closeTime": "17:00"
      },
      {
        "day": "sunday",
        "isOpen": false,
        "openTime": "08:00",
        "closeTime": "17:00"
      }
    ],
    "timezone": "Asia/Manila",
    "intervalMinutes": 60
  },
  "createdAt": "2026-04-13T10:01:16.911Z",
  "updatedAt": "2026-04-15T06:40:15.247Z",
  "serviceName": "Personal Care & Beauty"
}

Error Responses

401 Unauthorized — No valid token:

{
  "statusCode": 401,
  "message": "Access token is required to proceed."
}

404 Not Found — User has no organization:

{
  "statusCode": 404,
  "message": "Organization not found"
}

cURL Example

curl -X GET http://localhost:4001/api/v1/organizations \
  -H "Authorization: Bearer eyJhbGc..."

GET `/api/v1/tenant/:slug` — Get Organization by Slug (Public)

Auth: Public
Used by: cms-booki-web-app, customer-booki-web-app · Role: guest
organizationId: Resolved from :slug route param
Description: Retrieve organization details by URL slug (public lookup).

Request

GET /api/v1/tenant/janes-salon

Response (200 OK)

{
  "success": true,
  "organization": {
    "id": "69dcbeec1a79a4eac35bc721",
    "name": "Jane's Beauty Salon",
    "slug": "janes-salon",
    "service": "Personal Care & Beauty",
    "address": "123 Business Complex, Main Avenue, Doña Julia, Quezon City, Metro Manila, NCR 1100",
    "email": "owner1@example.com",
    "phone": "09171234567",
    "timezone": "Asia/Manila",
    "paymentMethods": {
      "maya": true,
      "cash": false
    }
  }
}

Error Responses

404 Not Found — Slug doesn't exist:

{
  "statusCode": 404,
  "message": "Organization not found"
}

cURL Example

curl -X GET http://localhost:4001/api/v1/tenant/janes-salon

GET `/api/v1/tenant?slug=:slug` — Resolve Tenant via Query Param

Auth: Public
Used by: cms-booki-web-app, customer-booki-web-app · Role: guest
organizationId: Resolved from ?slug query param
Description: Alternative way to resolve tenant using query parameter.

Request

GET /api/v1/tenant?slug=janes-salon

Response (200 OK)

Same as /api/v1/tenant/:slug above.

cURL Example

curl -X GET "http://localhost:4001/api/v1/tenant?slug=janes-salon"

GET `/api/v1/tenant` (with header) — Resolve Tenant via Header

Auth: Public
Used by: cms-booki-web-app, customer-booki-web-app · Role: guest
organizationId: Resolved from X-Tenant-Slug header
Description: Resolve tenant using X-Tenant-Slug header.

Request

GET /api/v1/tenant
Header: X-Tenant-Slug: janes-salon

Response (200 OK)

Same as /api/v1/tenant/:slug above.

cURL Example

curl -X GET http://localhost:4001/api/v1/tenant \
  -H "X-Tenant-Slug: janes-salon"

Organization Structure

Field	Type	Description
`_id`	ObjectId	Organization ID
`name`	string	Business name
`slug`	string	URL-friendly slug (unique, lowercase)
`service`	ObjectId	Booking service category
`businessPermit`	string	Gov't permit number
`businessRegistration`	string	Registration number
`businessAddress`	object	Full business address
`branches`	array	Branch IDs
`owner`	object	Owner user details
`createdAt`	ISODate	Creation timestamp
`updatedAt`	ISODate	Last update timestamp

Slug Resolution Flow

Customer visits https://janes-salon.booki.app
Browser extracts janes-salon from hostname
API queries: db.organizations.findOne({ slug: "janes-salon" })
Tenant context set on request (req.tenant.organizationId)
All downstream queries scoped by organization

See Multi-Tenancy Guide for details.

Notes

Slugs are unique across all organizations; validation enforces this constraint.
Slug format: lowercase alphanumeric + hyphens (e.g., janes-salon, acme-services).
Public organization lookups don't require authentication.
Organization data is cached for performance; updates propagate within seconds.

Organizations - Business Hours

Get and update business operating hours, timeslots, and availability.

Organizations - Packages

Create, list, update, and delete service packages (owner endpoints).