Consultation Module API & Integration Guide

Consultation API contracts for admin slot and booking operations plus customer booking flows.

Audience: Mobile/web frontend developers Scope: Booking endpoints, error codes

1. How to Read / Quick Metadata

Module: Consultation
Auth models:
- Customer slot list + booking create: public (@Public) with optional JWT for book
- Customer booking history: JwtAuthGuard
- Admin routes: JwtAuthGuard + RoleGuard + @Permissions(...)
Primary base URLs:
- Customer: /api/consultations
- Mobile-composed customer: /api/mobile/consultations
- Admin slots: /api/admin/consultations/slots
- Admin bookings: /api/admin/consultations/bookings
Response envelope: successful endpoints return ResponseDto<T>
Swagger tags used by controllers:
- Consultation (Mobile)
- Consultation Slots (Admin)
- Consultation Bookings (Admin)

2. High-Level Overview

Consultation API is split into:

admin slot inventory management
admin booking management and contacted-state updates
public/customer slot discovery and booking submission
authenticated customer booking history

Booking creation immediately persists the booking and queues notifications asynchronously.

3. Core Concepts and Terminology

slot: consultation availability record in consultation_slot
booking: customer consultation request in consultation_booking
booking status: pending or contacted
isBooked flag: derived field on slot list to indicate booking existence
bulk slot generation: interval-based slot creation from weekday/date rules
notification fanout: booking success queues notification.send_email and optional notification.send_push

4. Route Summary

4.1 Customer / Mobile

Method	Path	Behavior
`GET`	`/api/consultations/slots`	Lists available slots (public)
`POST`	`/api/consultations/book`	Books a slot (public, optional auth link)
`GET`	`/api/consultations/bookings`	Lists own bookings (JWT required)

Mobile-composed equivalents are available under /api/mobile/consultations/....

4.2 Admin Slots

Method	Path	Permission
`GET`	`/api/admin/consultations/slots`	`ConsultationSlots_READ`
`GET`	`/api/admin/consultations/slots/:id`	`ConsultationSlots_READ`
`POST`	`/api/admin/consultations/slots`	`ConsultationSlots_CREATE`
`PATCH`	`/api/admin/consultations/slots/:id`	`ConsultationSlots_UPDATE`
`DELETE`	`/api/admin/consultations/slots/:id`	`ConsultationSlots_DELETE`

4.3 Admin Bookings

Method	Path	Permission
`GET`	`/api/admin/consultations/bookings`	`ConsultationBookings_READ`
`GET`	`/api/admin/consultations/bookings/:id`	`ConsultationBookings_READ`
`PATCH`	`/api/admin/consultations/bookings/:id/status`	`ConsultationBookings_UPDATE`

Route Details

List Slots

Aspect	Details
Endpoint	`GET /api/consultations/slots` or `/api/mobile/consultations/slots`
Auth	Public
Request	query params: date, isActive
Response	`ResponseDto<SlotDto[]>`
Errors	-

Book Slot

Aspect	Details
Endpoint	`POST /api/consultations/book` or `/api/mobile/consultations/book`
Auth	Optional JWT
Request	`"" slotId: number, name: string, email: string, phone?: string ""`
Response	`ResponseDto<BookingDto>`
Errors	400 slot unavailable, 400 past date

5. Query Parameters

5.1 Customer slots (`GET /api/consultations/slots`)

Param	Type	Default
`page`	number	`1`
`size`	number	`20`
`pagination`	boolean	`true`
`date`	`YYYY-MM-DD`	optional
`sort`	`date` \| `startTime`	`date`
`order`	`asc` \| `desc`	`asc`

5.2 Customer bookings (`GET /api/consultations/bookings`)

Param	Type	Default
`page`	number	`1`
`size`	number	`20`
`pagination`	boolean	`true`
`status`	`pending` \| `contacted`	optional

5.3 Admin slots (`GET /api/admin/consultations/slots`)

Param	Type	Default
`page`	number	`1`
`size`	number	`20`
`pagination`	boolean	`true`
`date`	`YYYY-MM-DD`	optional
`isActive`	boolean	optional
`sort`	`date` \| `startTime` \| `createdAt`	`date`
`order`	`asc` \| `desc`	`asc`

5.4 Admin bookings (`GET /api/admin/consultations/bookings`)

Param	Type	Default
`page`	number	`1`
`size`	number	`20`
`pagination`	boolean	`true`
`status`	`pending` \| `contacted`	optional
`slotDate`	`YYYY-MM-DD`	optional
`search`	string	optional
`sort`	`bookedAt` \| `slotDate` \| `fullName`	`bookedAt`
`order`	`asc` \| `desc`	`desc`

6. Response Shape Examples

6.1 Booking create request

"
  "fullName": "John Doe",
  "contactNum": "+9779841234567",
  "email": "john.doe@example.com",
  "message": "I need guidance for NEPSE portfolio allocation.",
  "slotId": 12
"

6.2 Slot list item

"
  "id": 1,
  "date": "2026-04-15",
  "startTime": "10:00:00",
  "endTime": "11:00:00",
  "isActive": true,
  "isBooked": false,
  "createdAt": "2026-04-01T00:00:00.000Z"
"

6.3 Booking response

"
  "id": 1,
  "fullName": "John Doe",
  "email": "john.doe@example.com",
  "contactNum": "+9779841234567",
  "message": "I need guidance for NEPSE portfolio allocation.",
  "slotId": 12,
  "slotDate": "2026-04-15",
  "slotStartTime": "10:00:00",
  "slotEndTime": "11:00:00",
  "bookedAt": "2026-04-10T08:30:00.000Z",
  "bookingStatus": "pending"
"

7. Enums

7.1 `consultation_booking_status`

pending
contacted

7.2 Allowed weekdays for admin bulk creation

sun, mon, tue, wed, thu, fri, sat

8. Integration Diagram

9. Caching

Cache keyspaces:

consultation:customer:slots:list:

TTL env:

CONSULTATION_SLOTS_CACHE_TTL_SECONDS (default 300)

Invalidation triggers:

admin slot create/update/delete
customer booking create

10. Error Handling

All consultation API errors return the standard error envelope:

"
  "statusCode": 400,
  "errorCode": "CONSULTATION_SLOT_INACTIVE",
  "message": "Consultation slot is not active.",
  "timestamp": "2026-04-10T08:30:00.000Z",
  "path": "/api/consultations/book"
"

Representative error map:

HTTP	errorCode	Message
400	`CONSULTATION_SLOT_INACTIVE`	Consultation slot is not active.
400	`CONSULTATION_SLOT_PAST_DATE`	Cannot book a slot in the past.
400	`CONSULTATION_SLOT_ALREADY_BOOKED`	Slot is already booked.
400	`CONSULTATION_BOOKING_SLOT_RESTRICTED`	Cannot delete slot that has bookings. Please deactivate instead.
404	`CONSULTATION_SLOT_NOT_FOUND`	Consultation slot not found.
404	`CONSULTATION_BOOKING_NOT_FOUND`	Consultation booking not found.
409	`CONSULTATION_SLOT_CONFLICT`	Slot conflict (duplicate slot or invalid slot-time window).
429	`RATE_LIMIT_EXCEEDED`	Too many requests. Please try again later.

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

11. Endpoint Reference + Payload Cheatsheet

11.1 Payload Cheatsheet Table (Every Endpoint)

Method	Path	Auth / Permission	Request DTO / Params	Success DTO	Notes
GET	`/api/consultations/slots`	Public	`QuerySlotsDto` "" page?, size?, pagination?, date?, sort?, order? ""	`SlotDto[]` paginated	Lists available consultation slots; public access
GET	`/api/mobile/consultations/slots`	Public	`QuerySlotsDto` "" page?, size?, pagination?, date?, sort?, order? ""	`SlotDto[]` paginated	Mobile-composed equivalent of slot list
POST	`/api/consultations/book`	Optional JWT	`CreateBookingDto` "" slotId: number, fullName: string, email: string, contactNum: string, message?: string ""	`BookingDto`	Books a slot; optional auth links booking to user
POST	`/api/mobile/consultations/book`	Optional JWT	`CreateBookingDto` "" slotId: number, fullName: string, email: string, contactNum: string, message?: string ""	`BookingDto`	Mobile-composed equivalent of book slot
GET	`/api/consultations/bookings`	User JWT	`QueryBookingsDto` "" page?, size?, pagination?, status? ""	`BookingDto[]` paginated	Lists current user's booking history
GET	`/api/mobile/consultations/bookings`	User JWT	`QueryBookingsDto` "" page?, size?, pagination?, status? ""	`BookingDto[]` paginated	Mobile-composed equivalent of bookings list
GET	`/api/admin/consultations/slots`	Admin + `ConsultationSlots_READ`	`QuerySlotsAdminDto` "" page?, size?, pagination?, date?, isActive?, sort?, order? ""	`SlotDto[]` paginated	Admin lists all slots with filters
GET	`/api/admin/consultations/slots/:id`	Admin + `ConsultationSlots_READ`	path: id (int)	`SlotDto`	Admin fetches single slot detail
POST	`/api/admin/consultations/slots`	Admin + `ConsultationSlots_CREATE`	`CreateSlotDto` "" date: string, startTime: string, endTime: string, isActive?: boolean ""	`SlotDto`	Admin creates new slot
PATCH	`/api/admin/consultations/slots/:id`	Admin + `ConsultationSlots_UPDATE`	path: id (int), body: `UpdateSlotDto` "" date?: string, startTime?: string, endTime?: string, isActive?: boolean ""	`SlotDto`	Admin updates existing slot
DELETE	`/api/admin/consultations/slots/:id`	Admin + `ConsultationSlots_DELETE`	path: id (int)	`"" deleted: boolean ""`	Admin deletes slot; fails if has bookings
GET	`/api/admin/consultations/bookings`	Admin + `ConsultationBookings_READ`	`QueryBookingsAdminDto` "" page?, size?, pagination?, status?, slotDate?, search?, sort?, order? ""	`BookingDto[]` paginated	Admin lists all bookings with filters
GET	`/api/admin/consultations/bookings/:id`	Admin + `ConsultationBookings_READ`	path: id (int)	`BookingDto`	Admin fetches single booking detail
PATCH	`/api/admin/consultations/bookings/:id/status`	Admin + `ConsultationBookings_UPDATE`	path: id (int), body: `UpdateBookingStatusDto` "" status: "pending" \| "contacted" ""	`BookingDto`	Admin updates booking contacted status

11.1.1 Customer Slots Endpoint Query Variations

Method	Path	Query Parameters	Notes
GET	`/api/consultations/slots`	(no params)	Default: page=1, size=20, sort=date asc
GET	`/api/consultations/slots`	`?page=2&size=10`	Custom pagination
GET	`/api/consultations/slots`	`?date=2026-04-15`	Filter by specific date
GET	`/api/consultations/slots`	`?sort=startTime&order=desc`	Sort by start time descending
GET	`/api/consultations/slots`	`?pagination=false`	Returns all records

11.1.2 Customer Bookings Endpoint Query Variations

Method	Path	Query Parameters	Notes
GET	`/api/consultations/bookings`	(no params)	Default: page=1, size=20, sort=bookedAt desc
GET	`/api/consultations/bookings`	`?status=pending`	Filter by pending status
GET	`/api/consultations/bookings`	`?status=contacted`	Filter by contacted status
GET	`/api/consultations/bookings`	`?page=1&size=50`	Custom pagination

11.1.3 Admin Slots Endpoint Query Variations

Method	Path	Query Parameters	Notes
GET	`/api/admin/consultations/slots`	(no params)	Default: page=1, size=20, sort=date asc
GET	`/api/admin/consultations/slots`	`?isActive=true`	Filter by active status
GET	`/api/admin/consultations/slots`	`?date=2026-04-15`	Filter by specific date
GET	`/api/admin/consultations/slots`	`?sort=createdAt&order=desc`	Sort by creation date
GET	`/api/admin/consultations/slots`	`?page=3&size=100`	Custom pagination

11.1.4 Admin Bookings Endpoint Query Variations

Method	Path	Query Parameters	Notes
GET	`/api/admin/consultations/bookings`	(no params)	Default: page=1, size=20, sort=bookedAt desc
GET	`/api/admin/consultations/bookings`	`?status=pending`	Filter pending bookings
GET	`/api/admin/consultations/bookings`	`?status=contacted`	Filter contacted bookings
GET	`/api/admin/consultations/bookings`	`?slotDate=2026-04-15`	Filter by slot date
GET	`/api/admin/consultations/bookings`	`?search=john`	Search by name/email/phone
GET	`/api/admin/consultations/bookings`	`?sort=slotDate&order=asc`	Sort by slot date
GET	`/api/admin/consultations/bookings`	`?search=john&status=pending`	Combined search and filter

11.1.5 Booking Create Request Variations

Method	Path	Request Body	Notes
POST	`/api/consultations/book`	`"" "slotId": 12, "fullName": "John Doe", "email": "john@example.com", "contactNum": "+9779841234567" ""`	Basic booking without message
POST	`/api/consultations/book`	`"" "slotId": 12, "fullName": "Jane Smith", "email": "jane@example.com", "contactNum": "+9779847654321", "message": "Need help with portfolio" ""`	Booking with message
POST	`/api/mobile/consultations/book`	`"" "slotId": 12, "fullName": "John Doe", "email": "john@example.com", "contactNum": "+9779841234567" ""`	Mobile equivalent

11.1.6 Slot Response Field Variations

Field	Type	Notes
id	number	Unique slot ID
date	string (YYYY-MM-DD)	Slot date
startTime	string (HH:MM:SS)	Slot start time
endTime	string (HH:MM:SS)	Slot end time
isActive	boolean	Whether slot is available
isBooked	boolean	Derived field; true if already booked
createdAt	ISO8601	Slot creation timestamp

11.1.7 Booking Response Field Variations

Field	Type	Notes
id	number	Unique booking ID
fullName	string	Customer full name
email	string	Customer email
contactNum	string	Customer phone
message	string \| null	Optional customer message
slotId	number	Referenced slot ID
slotDate	string	Derived from slot
slotStartTime	string	Derived from slot
slotEndTime	string	Derived from slot
bookedAt	ISO8601	Booking creation time
bookingStatus	string	pending/contacted

11.1.8 Error Response Variations

HTTP	errorCode	Trigger
400	`CONSULTATION_SLOT_INACTIVE`	Slot is not active
400	`CONSULTATION_SLOT_PAST_DATE`	Attempting to book past slot
400	`CONSULTATION_SLOT_ALREADY_BOOKED`	Slot already has booking
400	`CONSULTATION_BOOKING_SLOT_RESTRICTED`	Delete slot with bookings
404	`CONSULTATION_SLOT_NOT_FOUND`	Slot ID does not exist
404	`CONSULTATION_BOOKING_NOT_FOUND`	Booking ID does not exist
409	`CONSULTATION_SLOT_CONFLICT`	Duplicate or invalid slot time
429	`RATE_LIMIT_EXCEEDED`	Too many requests

11.1.9 Cache Invalidation Variations

Trigger	Invalidated Key Pattern
POST /admin/consultations/slots	`consultation:customer:slots:list:*`
PATCH /admin/consultations/slots/:id	`consultation:customer:slots:list:*`
DELETE /admin/consultations/slots/:id	`consultation:customer:slots:list:*`
POST /consultations/book	`consultation:customer:slots:list:*`

11.1.10 Admin Slot Create/Update Variations

Method	Path	Request Body	Notes
POST	`/api/admin/consultations/slots`	`"" "date": "2026-04-20", "startTime": "09:00:00", "endTime": "10:00:00", "isActive": true ""`	Create morning slot
POST	`/api/admin/consultations/slots`	`"" "date": "2026-04-20", "startTime": "14:00:00", "endTime": "15:00:00", "isActive": true ""`	Create afternoon slot
PATCH	`/api/admin/consultations/slots/5`	`"" "isActive": false ""`	Deactivate slot
PATCH	`/api/admin/consultations/slots/5`	`"" "startTime": "10:00:00", "endTime": "11:00:00" ""`	Reschedule slot

11.1.11 Booking Status Update Variations

Method	Path	Request Body	Notes
PATCH	`/api/admin/consultations/bookings/1/status`	`"" "status": "contacted" ""`	Mark as contacted
PATCH	`/api/admin/consultations/bookings/1/status`	`"" "status": "pending" ""`	Revert to pending

Consultation Module API & Integration Guide

On this page