Fetch Recent Bookings

Bookings Read Only

Retrieve the most recently created bookings using cursor-based pagination. Ideal for syncing new bookings incrementally or building real-time dashboards.

Pagination

Cursor-based for efficiency

Auth

Bearer token required

Use cases

Incremental sync · Live feeds · Webhooks fallback

---

Endpoint overview

GET Authenticated

URL: {{base_url}}/employee/booking/fetch-recent-bookings

• Requires a valid bearer token in the Authorization header.
• Uses cursor-based pagination for efficient data retrieval.
• Returns bookings in reverse chronological order.

---

Required headers

Header	Value
Authorization	Bearer {{token}}

---

Query parameters

Parameter	Type	Required	Description
limit	number	No	Maximum number of bookings to return (default: 10, max: 100)
cursor	string	No	ISO timestamp cursor from previous response for pagination
bookingType	string	No	Filter by booking type: IN (international) or LC (local)

---

Sample request

GET /employee/booking/fetch-recent-bookings?limit=7&cursor=2024-06-25T15:10:12.123Z&bookingType=IN HTTP/1.1
Host: {{ base_url }}
Authorization: Bearer {{ token }}
Accept: application/json

---

Response

{
  "success": true,
  "data": {
    "bookings": [
      {
        "_id": "69090bfcabc57c5eb35b0f15",
        "searchId": "72285500",
        "sourcePlatform": "AAJ-Send",
        "receiver": {
          "contact": {
            "name": "Rebecca Owolabi",
            "phone": "+442030484377",
            "email": "o.rebecca@gmail.com"
          },
          "addressDetails": {
            "city": "Leeds",
            "country": "United Kingdom",
            "countryCode": "GB"
          }
        },
        "sender": {
          "contact": {
            "name": "Lanre Ogundele",
            "phone": "+2348036415243"
          },
          "addressDetails": {
            "city": "Ibadan",
            "country": "Nigeria",
            "countryCode": "NG"
          }
        },
        "weight": 25,
        "numberOfPackages": 1,
        "totalAmount": 6988,
        "paid": true,
        "bookingState": 1,
        "orderState": 1,
        "bookingDate": "2025-11-03T20:09:32.054Z",
        "createdAt": "2025-11-03T20:09:32.057Z"
      }
    ],
    "nextCursor": "2025-11-03T20:09:32.057Z",
    "hasMore": true
  },
  "status": 200,
  "message": "Paginated bookings fetched successfully",
  "timestamp": "2025-11-10T14:44:53.297Z"
}

---

Response (empty result)

When no bookings match the criteria:

{
  "success": true,
  "data": {
    "bookings": [],
    "nextCursor": null,
    "hasMore": false
  },
  "status": 200,
  "message": "Paginated bookings fetched successfully",
  "timestamp": "2025-11-10T14:44:53.297Z"
}

---

Key response fields

Field	Type	Description
success	boolean	Indicates whether the request was successful
data.bookings	array	Array of booking objects (summary view)
data.nextCursor	string\|null	ISO timestamp to use as cursor for next page; null if no more pages
data.hasMore	boolean	Whether additional pages are available
status	number	HTTP status code (200 for success)
message	string	Response message
timestamp	string	ISO timestamp of the response

---

Pagination workflow

1. Initial request: Call without cursor to get the most recent bookings
2. Check hasMore: If true, more bookings are available
3. Next page: Use nextCursor value as the cursor parameter in your next request
4. Repeat: Continue until hasMore is false

// Example: Fetch all recent bookings
let cursor = null;
let allBookings = [];

do {
  const url = cursor
    ? `/employee/booking/fetch-recent-bookings?limit=50&cursor=${cursor}`
    : `/employee/booking/fetch-recent-bookings?limit=50`;

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  });
  const data = await response.json();

  allBookings.push(...data.data.bookings);
  cursor = data.data.nextCursor;
} while (data.data.hasMore);

---

Error responses

Unauthorized

{
  "success": false,
  "status": 401,
  "message": "Invalid or expired token",
  "timestamp": "2025-11-10T14:44:53.297Z"
}

---

Tip: For real-time updates, consider webhooks. Use this endpoint as a fallback for catching up on missed events or for initial data synchronization.