Universal Travel Booking Requests & Manager Approvals API

Overview

Enables employees (USER) to raise travel booking requests across all product verticals (Flights, Hotels, Cabs, Insurance, Forex). Requests are stored in a dedicated BookingRequest table and routed to their respective manager for review.

Upon manager approval (or automated auto-approval if totalCost is less than or equal to the employee's EmployeeBand.autoApprovalLimit), the system automatically executes the supplier booking (https://apitest-hotel-booker.tripjack.com/oms/v3/hotel/book) with PII delivery data masked for user privacy, and creates a confirmed record in the primary Booking table.

Endpoints:
- POST /api/booking-requests/create — Employee submits a travel booking request
- GET/POST /api/booking-requests/company-list — Company Admin lists all booking requests of company (where.companyId)
- GET/POST /api/booking-requests/manager-list — Manager User lists requests of managed users (where.companyId & where.managerId)
- GET/POST /api/booking-requests/user-list — Employee User lists personal booking requests (where.userId)
- GET/POST /api/booking-requests/list — General filterable booking requests list
- POST /api/booking-requests/approve — Manager approves or rejects a request
HTTP Methods: GET and POST
Headers:
- Content-Type: application/json
- Authorization: Bearer <token> (Optional)

1. Create Booking Request (`POST /api/booking-requests/create`)

Request Body Parameters

Field	Type	Required	Description
`travelType`	`enum`	Required	`FLIGHT`, `HOTEL`, `CAB`, `INSURANCE`, or `FOREX`
`providerBookingId`	`string`	Optional	Supplier review booking ID (e.g. `"TGS208420065548"`)
`totalCost`	`number`	Required	Total booking amount
`currency`	`string`	Optional	Default: `"INR"`
`title`	`string`	Optional	Descriptive summary title
`travelPurpose`	`string`	Optional	Corporate travel purpose
`costCenterCode`	`string`	Optional	Cost center code
`departureDate`	`string`	Optional	Travel start date (`YYYY-MM-DD`)
`returnDate`	`string`	Optional	Travel end date (`YYYY-MM-DD`)
`userId`	`string`	Optional	User ID of employee placing request
`managerId`	`string`	Optional	Approving manager ID
`roomTravellerInfo`	`array`	Optional	Passenger/Guest details array
`deliveryInfo`	`object`	Optional	Delivery contacts (`emails`, `contacts`, `code`)
`paymentInfos`	`array`	Optional	Payment breakdown array

Standardized `requestDataJson` Schemas by `travelType`

Every request formats requestDataJson into a standardized JSON structure with guaranteed keys based on travelType:

1. `HOTEL`

{
  "bookingMode": "INSTANT",
  "hid": "100234",
  "checkIn": "2026-10-01",
  "checkOut": "2026-10-03",
  "rooms": [{ "adults": 2, "children": 0 }],
  "correlationId": "corr_12345",
  "hotelName": "Grand Palace Resort",
  "roomTypeName": "Deluxe King Room",
  "ratePlanName": "Free Breakfast & Cancellation",
  "rawSupplierData": { ... }
}

2. `FLIGHT`

{
  "bookingMode": "INSTANT",
  "origin": "DEL",
  "destination": "BOM",
  "travelDate": "2026-10-01",
  "returnDate": "2026-10-05",
  "cabinClass": "ECONOMY",
  "airlineCode": "6E",
  "flightNumber": "6E-204",
  "pnr": "ABC1234",
  "rawSupplierData": { ... }
}

3. `CAB`

{
  "pickupLocation": "Terminal 3, Delhi Airport",
  "dropLocation": "Connaught Place, New Delhi",
  "pickupDateTime": "2026-10-01T10:00:00Z",
  "vehicleType": "SEDAN",
  "driverDetails": null,
  "rawSupplierData": { ... }
}

4. `INSURANCE`

{
  "policyType": "DOMESTIC",
  "startDate": "2026-10-01",
  "endDate": "2026-10-05",
  "paxCount": 2,
  "planName": "Comprehensive Travel Protect",
  "rawSupplierData": { ... }
}

5. `FOREX`

{
  "currency": "USD",
  "amount": 1000,
  "forexType": "CARD",
  "deliveryAddress": "Corporate Office, Mumbai",
  "rawSupplierData": { ... }
}

Example Request

{
  "travelType": "HOTEL",
  "providerBookingId": "TGS208420065548",
  "totalCost": 23486.76,
  "currency": "INR",
  "title": "Hotel Booking Request for Mumbai Business Trip",
  "travelPurpose": "Client Onboarding",
  "costCenterCode": "CC-SALES-01",
  "roomTravellerInfo": [
    {
      "travellerInfo": [
        { "ti": "Mr", "pt": "ADULT", "fN": "GENIUS", "lN": "WORLD", "pan": "AAACA1111A" },
        { "ti": "Master", "pt": "CHILD", "fN": "JAPANJOT", "lN": "SINGH", "pan": "AAACA1111A" }
      ]
    }
  ],
  "deliveryInfo": {
    "emails": ["employee@example.com"],
    "contacts": ["9876543210"],
    "code": ["+91"]
  },
  "paymentInfos": [{ "amount": 23486.76 }]
}

Response Example (201 Created)

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "requestRefNumber": "REQ-7X9A2-4821",
    "travelType": "HOTEL",
    "status": "PENDING",
    "totalCost": "23486.76",
    "currency": "INR",
    "title": "Hotel Booking Request for Mumbai Business Trip",
    "user": {
      "id": "usr-101",
      "firstName": "GENIUS",
      "lastName": "WORLD",
      "email": "employee@example.com"
    },
    "createdAt": "2026-09-10T12:50:00.000Z"
  },
  "message": "Travel booking request created successfully and assigned to manager"
}

2. Company Admin Booking Requests List (`GET/POST /api/booking-requests/company-list`)

Used by Company Admin to list all booking requests belonging to their company. Applies where.companyId = req.companyId (extracted automatically from authentication token or optional parameter).

Query / Body Parameters

Parameter	Type	Required	Description
`companyId`	`string`	Optional	Company UUID (Extracted automatically from token `req.companyId`)
`status`	`string`	Optional	Filter by status (`PENDING`, `APPROVED`, `REJECTED`)
`travelType`	`string`	Optional	Filter by vertical (`FLIGHT`, `HOTEL`, etc.)
`page`	`number`	Optional	Default `1`
`limit`	`number`	Optional	Default `20`

Example Request

GET /api/booking-requests/company-list?status=PENDING&page=1&limit=20

3. Manager Booking Requests List (`GET/POST /api/booking-requests/manager-list`)

Used by Manager to list all requests of users whom they are managing. Applies where.companyId and where.managerId (extracted automatically from authentication token or optional parameter).

Query / Body Parameters

Parameter	Type	Required	Description
`companyId`	`string`	Optional	Company UUID (Extracted automatically from token `req.companyId`)
`managerId` / `userId`	`string`	Optional	Manager User ID (Extracted automatically from token `req.userId`)
`status`	`string`	Optional	Filter by status (`PENDING`, `APPROVED`, `REJECTED`)
`travelType`	`string`	Optional	Filter by vertical (`FLIGHT`, `HOTEL`, etc.)
`page`	`number`	Optional	Default `1`
`limit`	`number`	Optional	Default `20`

Example Request

GET /api/booking-requests/manager-list?status=PENDING&page=1&limit=20

4. User Personal Booking Requests List (`GET/POST /api/booking-requests/user-list`)

Used by Employee User to list their own booking requests. Applies where.userId = req.userId (extracted automatically from authentication token). userId is NOT required in request body or query parameters.

Query / Body Parameters

Parameter	Type	Required	Description
`status`	`string`	Optional	Filter by status (`PENDING`, `APPROVED`, `REJECTED`)
`travelType`	`string`	Optional	Filter by vertical (`FLIGHT`, `HOTEL`, etc.)
`page`	`number`	Optional	Default `1`
`limit`	`number`	Optional	Default `20`

Example Request

GET /api/booking-requests/user-list?status=PENDING&page=1&limit=20

5. General Booking Requests List (`GET/POST /api/booking-requests/list`)

Query Parameters

Parameter	Type	Required	Description
`userId`	`string`	Optional	Filter requests created by a specific employee (`req.userId`)
`companyId`	`string`	Optional	Filter all requests belonging to a specific company (`req.companyId`)
`managerId`	`string`	Optional	Filter requests assigned to a manager
`status`	`string`	Optional	Filter by status (`PENDING`, `APPROVED`, `REJECTED`)
`travelType`	`string`	Optional	Filter by vertical (`FLIGHT`, `HOTEL`, etc.)
`page`	`number`	Optional	Default `1`
`limit`	`number`	Optional	Default `20`

Example Request

GET /api/booking-requests/list?status=PENDING&page=1&limit=10

3. Approve or Reject Request (`POST /api/booking-requests/approve`)

Request Body Parameters

Field	Type	Required	Description
`requestId`	`string`	Required	UUID of the `BookingRequest`
`action`	`enum`	Required	`"APPROVE"` or `"REJECT"`
`remarks`	`string`	Optional	Manager remarks/reason
`bookingMode`	`enum`	Optional	`"INSTANT"` (confirmed with payment) or `"HOLD"` (reserved without payment)

Example Request Body (Approval)

{
  "requestId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "action": "APPROVE",
  "remarks": "Approved within travel budget",
  "bookingMode": "INSTANT"
}

Response Example (200 OK)

{
  "success": true,
  "data": {
    "request": {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "requestRefNumber": "REQ-7X9A2-4821",
      "status": "APPROVED",
      "managerRemarks": "Approved within travel budget",
      "createdBookingId": "bk-998877"
    },
    "booking": {
      "id": "bk-998877",
      "bookingRefNumber": "BK-HOTEL-998877",
      "status": "CONFIRMED",
      "totalCost": "23486.76"
    }
  },
  "message": "Booking request approved and supplier booking confirmed successfully"
}

Overview​

1. Create Booking Request (POST /api/booking-requests/create)​

Request Body Parameters​

Standardized requestDataJson Schemas by travelType​

1. HOTEL​

2. FLIGHT​

3. CAB​

4. INSURANCE​

5. FOREX​

Example Request​

Response Example (201 Created)​

2. Company Admin Booking Requests List (GET/POST /api/booking-requests/company-list)​

Query / Body Parameters​

Example Request​

3. Manager Booking Requests List (GET/POST /api/booking-requests/manager-list)​

Query / Body Parameters​

Example Request​

4. User Personal Booking Requests List (GET/POST /api/booking-requests/user-list)​

Query / Body Parameters​

Example Request​

5. General Booking Requests List (GET/POST /api/booking-requests/list)​

Query Parameters​

Example Request​

3. Approve or Reject Request (POST /api/booking-requests/approve)​

Request Body Parameters​

Example Request Body (Approval)​

Response Example (200 OK)​

Overview

1. Create Booking Request (`POST /api/booking-requests/create`)

Request Body Parameters

Standardized `requestDataJson` Schemas by `travelType`

1. `HOTEL`

2. `FLIGHT`

3. `CAB`

4. `INSURANCE`

5. `FOREX`

Example Request

Response Example (201 Created)

2. Company Admin Booking Requests List (`GET/POST /api/booking-requests/company-list`)

Query / Body Parameters

Example Request

3. Manager Booking Requests List (`GET/POST /api/booking-requests/manager-list`)

Query / Body Parameters

Example Request

4. User Personal Booking Requests List (`GET/POST /api/booking-requests/user-list`)

Query / Body Parameters

Example Request

5. General Booking Requests List (`GET/POST /api/booking-requests/list`)

Query Parameters

Example Request

3. Approve or Reject Request (`POST /api/booking-requests/approve`)

Request Body Parameters

Example Request Body (Approval)

Response Example (200 OK)