Service Types API

Manage service types used to classify payments/transactions (e.g., Brokerage, Registration, Maintenance).

Base URL: /api/serviceTypes

Authentication: Requires an authenticated user (JWT cookie token).

Authorization (current behavior): The router does not declare role guards. However, GET / relies on req.user and applies company scoping unless the user is super-admin. In production, you should protect POST/PUT/DELETE with authorize(["admin"]) (recommended).

---

Data Model (response shape)

Objects returned by GET / are joined with creator user and company names:

{
  "id": 12,
  "name": "Registration",
  "isActive": true,
  "description": "DLD registration fees",
  "createdBy": "Fatima Ali",
  "createdAt": "2025-01-12T14:20:13.000Z",
  "company": "MyHomePlan Dubai"
}

Fields persisted in the service_types table (for create/update):

Field	Type	Required	Notes
name	string	yes	Unique per company (enforced logically).
description	string	no	Free text.
company	number	yes (POST)	Company ID (foreign key).
isActive	boolean	no (PUT)	Defaults to true on create.

---

Endpoints

List Service Types

GET /

Returns service types filtered by optional query and company. If company is not provided and the user is not super-admin, results are restricted to the user's allowedCompanies.

Query Parameters

Name	Type	Description
query	string	Case-insensitive match on name.
company	number	Company ID. If omitted, non–super-admins are scoped to access.

Responses

• 200 OK — Array of service type records (see model above).
• 500 Internal Server Error — On unexpected failures.

Example

curl -X GET "https://api.example.com/api/serviceTypes?query=reg&company=3" \
  --cookie "token=YOUR_JWT_TOKEN"

[
  {
    "id": 7,
    "name": "Registration",
    "isActive": true,
    "description": "DLD",
    "createdBy": "System",
    "createdAt": "2024-06-10T09:11:12.000Z",
    "company": "MyHomePlan Dubai"
  }
]

---

Create Service Type

POST /

Creates a new service type for a company. Defaults isActive to true.

Request Body

{
  "name": "Brokerage",
  "description": "Agent commission",
  "company": 3
}

Responses

• 201 Created

  { "message": "ServiceTypes created successfully" }

• 500 Internal Server Error — On failure to insert.

Example

curl -X POST https://api.example.com/api/serviceTypes \
  -H "Content-Type: application/json" \
  --cookie "token=YOUR_JWT_TOKEN" \
  -d '{
        "name": "Brokerage",
        "description": "Agent commission",
        "company": 3
      }'

---

Update Service Type

PUT /:id

Updates fields for an existing service type.

Path Parameters

Name	Type	Description
id	number	Service type ID.

Request Body (any subset)

{
  "name": "Registration",
  "description": "Land Department fees",
  "isActive": false
}

Responses

• 200 OK

  { "message": "ServiceTypes updated successfully" }

• 404 Not Found — If the id does not exist.

• 500 Internal Server Error — On update failures.

Example

curl -X PUT https://api.example.com/api/serviceTypes/12 \
  -H "Content-Type: application/json" \
  --cookie "token=YOUR_JWT_TOKEN" \
  -d '{ "isActive": false }'

---

Delete Service Type

DELETE /:id

Deletes a service type.

Note: Hard delete via SQL DELETE is performed.

Path Parameters

Name	Type	Description
id	number	Service type ID.

Responses

• 200 OK

  { "message": "ServiceTypes deleted successfully" }

• 500 Internal Server Error — On delete failures.

Example

curl -X DELETE https://api.example.com/api/serviceTypes/12 \
  --cookie "token=YOUR_JWT_TOKEN"

---

Notes & Behavior

• Company scoping (GET): If company is omitted, non–super-admin users only see records in companies listed in req.user.allowedCompanies.
• RBAC recommendation: Align with Account Types protections and guard POST/PUT/DELETE with authorize(["admin"]).
• Joins in GET: createdBy and company are returned as names (from users and companies) rather than IDs.
• No pagination: The endpoint returns all matches; add pagination if datasets grow large.

Error Model

Errors return a JSON object with message (string). Example:

{ "message": "ServiceTypes not found" }

---

Changelog

• v1.0 — Initial documentation covering list/create/update/delete.