The Voya API is a RESTful tour booking service built with Node.js, Express, and MongoDB. It allows users to browse available tours, leave reviews, manage their bookings, and handle account authentication securely. This API supports role-based access control (admin, lead-guide, guide, user) and includes robust validation, error handling, and geospatial queries.
\nThis documentation provides details on all available endpoints, including:
\nPublic and protected routes
\nRole-based permissions
\nQuery and path parameters
\nRequest/response examples
\nAuthenticated workflows using JWT
\nAuthentication is required for most routes. Use the /users/login or /users/signup endpoints to obtain a JWT token, and include it in the Authorization header as Bearer .
Description: Fetches all available tours with query/filter options.
Auth Required: ❌
Query Parameters: sort, fields, limit, page, etc.
Response: List of tours
Supports easy, medium, hard
\n","type":"text/plain"},"key":"difficulty","value":"easy"},{"disabled":true,"key":"page","value":"1"},{"disabled":true,"key":"limit","value":"2"},{"disabled":true,"description":{"content":"Query for Tour Duration. Supports lte, lt, gte, gt operators
\n","type":"text/plain"},"key":"duration[gte]","value":"10"},{"disabled":true,"key":"price[lt]","value":"1500"},{"disabled":true,"key":"sort","value":"price,-ratingsAverage"},{"disabled":true,"description":{"content":"Fields available to select from: [name,duration,difficulty,price,ratingsAverage,summary,maxGroupSize,startDates,description ]
Description: Fetches details for a specific tour by ID.
Auth Required: ❌
Response: Tour object
Description: Creates a new tour.
Auth Required: ✅ (Admin or Lead Guide)
Body Parameters: name, price, duration, summary, etc.
Response: New tour object
Description: Updates a tour’s data by ID.
Auth Required: ✅ (Admin or Lead Guide)
Response: Updated tour object
Description: Deletes a tour by ID.
Auth Required: ✅ (Admin or Lead Guide)
Response: Success message
Description: Fetches top 5 cheapest tours based on price and ratings.
Auth Required: ❌
Response: List of top 5 tours
Description: Shows the monthly plan of tours for a specific year.
Auth Required: ✅ (Admin or Lead Guide)
Params: year (e.g., 2025)
Response: Monthly grouped tours
Description: Provides statistical data about tours (avg price, ratings, etc.)
Auth Required: ✅ (Admin or Lead Guide)
Response: Aggregated tour stats
Description: Find tours within a specific radius of a location.
Auth Required: ❌
Params:
distance: Numeric value (e.g., 50)
latlng: latitude and longitude (e.g., 34.111745,-118.113491)
unit: \"mi\" or \"km\"
Response: List of tours in area
\n","urlObject":{"path":["v1","tours","tours-within","233","center","34.111745,-118.113491","unit","mi"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"d33a560c-ff60-4e43-a71f-24415d41d9d7"},{"name":"Get Tours Distances","id":"3308b493-3e46-4ca4-a6b4-3f8baa7ba76d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/tours/distances/34.111745,-118.113491/unit/mi","description":"Description: Get distances from a point to all tours.
Auth Required: ❌
Params:
latlng: Latitude and longitude
unit: \"mi\" or \"km\"
Response: Array with tour distances
\n","urlObject":{"path":["v1","tours","distances","34.111745,-118.113491","unit","mi"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"3308b493-3e46-4ca4-a6b4-3f8baa7ba76d"}],"id":"e8b957a9-9c60-4c0c-8448-6a8c7a057fc8","description":"Description:
\n\n\nEndpoints related to managing and retrieving tour data. These routes allow users to fetch all tours, get individual tour details, and access specialized queries like top cheapest tours or tours within a certain location. Admins and guides can also create, update, or delete tours. Some routes are public, while others require
\nadminorlead-guideprivileges.
Key Features:
\nGet all tours with filtering, sorting, pagination
\nCreate, update, delete tours (admin/guide only)
\nAggregation endpoints for stats & monthly plans
\nGeospatial queries (within radius, distances)
\nDescription: Get all reviews across all tours.
Auth Required: ✅ Yes
Response: List of reviews
Ranges from 1 (lowest) to 5 (highest)
\n","type":"text/plain"},"key":"rating","value":"4"}],"variable":[]}},"response":[],"_postman_id":"d92727bb-42a3-400a-9deb-3a14f25de175"},{"name":"Get Review","id":"3895dff5-81bf-40f4-b7c4-b4f4092c5874","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/reviews/5c8a3c3b14eb5c17645c9135","description":"Description: Get a specific review by its ID.
Auth Required: ✅ Yes
Response: Review object
Description: Create a new review (user must be booked on the tour).
Auth Required: ✅ (User)
Body Parameters:
review: Text
rating: Number (1–5)
tour: ID of tour
user: ID of user
Response: Review object
\n","urlObject":{"path":["v1","reviews",""],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"3238856e-6a01-45ae-a2a8-4eb441f8106d"},{"name":"Update Review","id":"c19b51a2-c878-44dd-873d-06077dbe3785","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"PATCH","header":[],"body":{"mode":"raw","raw":"{\n \"rating\": 4\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/reviews/6822dcd601e4039bb47d585b","description":"Description: Update a review you created.
Auth Required: ✅ (User who created the review or Admin)
Response: Updated review object
Description: Delete a review by ID.
Auth Required: ✅ (User who created the review or Admin)
Response: Success message
Description:
\n\n\nThese endpoints provide CRUD operations for tour reviews. Users can create reviews for tours they've booked, and view or manage reviews depending on their role. Only the review owner or an admin can update or delete a review. Authenticated users can post reviews for a specific tour.
\n
Key Features:
\nPost reviews linked to tours
\nView all reviews or a specific review
\nUpdate/delete own reviews (or as admin)
\nDescription: Post a new review directly to a tour.
Auth Required: ✅ (User)
Response: Created review object
Description: Get all reviews for a specific tour.
Auth Required: ✅
Response: List of reviews for that tour
Description:
\n\n\nThese nested routes provide a convenient way to interact with reviews based on a specific tour using nested routing. They follow the format:
\n/tours/:tourId/reviewsThis enables consumers to create and retrieve reviews for a specific tour without needing to know review IDs.
Key Features:
\nPOST /tours/:tourId/reviews: Add a review to a specific tour
GET /tours/:tourId/reviews: Get all reviews for a specific tour
Description: Retrieves all users.
Auth Required: ✅ (Admin)
Response: List of users
Select from: [ admin, user, guide, lead-guide ]
\n","type":"text/plain"},"key":"role","value":"admin"}],"variable":[]}},"response":[],"_postman_id":"361d8726-9d53-4735-9a36-f2dfbe551bc4"},{"name":"Get User","id":"e2965a68-3592-4919-ae65-965fde635547","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/users/6","description":"Description: Get a single user by ID.
Auth Required: ✅ (Admin)
Response: User object
Description: Updates a user’s role or data by ID.
Auth Required: ✅ (Admin)
Response: Updated user object
Description: Deletes a user account by ID.
Auth Required: ✅ (Admin)
Response: Success message
Description: Retrieves the currently logged-in user's profile.
Auth Required: ✅ (User)
Response: User object
Description: Allows the user to update their own data (name or email).
Auth Required: ✅ (User)
Body Parameters:
name / emailResponse: Updated user object
\n","urlObject":{"path":["v1","users","updateMe"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"68fb1a03-d93d-4af9-bee8-e7126091548f"},{"name":"Delete Current User","id":"2fcbba00-d522-48a5-8eb2-c73ba0484261","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"DELETE","header":[],"url":"{{URL}}api/v1/users/deleteMe","description":"Description: Deactivates the currently authenticated user account.
Auth Required: ✅ (User)
Response: Success message
Description:
\n\n\nEndpoints for user management and administrative control over user accounts. These routes allow viewing and modifying user data, either by the user themselves or by an admin. Users can manage their profiles, while admins have full access to all user records.
\n
Key Features:
\nView, update, and delete users (admin-only)
\nUsers can update/delete their own profiles
\nPassword update endpoint (PATCH /updateMyPassword) available here.
Description: Register a new user account.
Auth Required: ❌
Body Parameters:
name: string – Full name (required)
email: string – User email (required)
password: string – User password (required)
passwordConfirm: string – Must match password
role: string - Defaults to user if not provided
Response: User data with JWT token
\n","urlObject":{"path":["v1","users","signup"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"4f37fa56-78c5-4e7d-963c-98d875cb6e86"},{"name":"Login User","event":[{"listen":"test","script":{"id":"06a5a16a-aa30-4de4-b4d1-ef0517e2f85e","exec":["postman.setEnvironmentVariable(\"jwt\", JSON.parse(responseBody).token);"],"type":"text/javascript","packages":{}}}],"id":"6d1bfc44-f2b0-487c-adc7-9c2949580cdc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"email\": \"admin@voya.io\",\n \"password\": \"{{password}}\"\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/users/login","description":"Description: Log in a registered user and receive a JWT token.
Auth Required: ❌
Body Parameters:
email: string
password: string
Response: User data with JWT token
\n","urlObject":{"path":["v1","users","login"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"6d1bfc44-f2b0-487c-adc7-9c2949580cdc"},{"name":"User Forgot Password","event":[{"listen":"test","script":{"id":"c6b08c27-1064-4da7-8faa-3ca422693d5f","exec":[""],"type":"text/javascript","packages":{}}}],"id":"b46adaf4-81b9-429f-98f5-482422996c81","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"email\": \"hello@toshita.io\"\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/users/forgotPassword","description":"Description: Sends a password reset link to the user's email.
Auth Required: ❌
Body Parameters:
email: string – Registered user emailResponse: Success message with token sent to email
\n","urlObject":{"path":["v1","users","forgotPassword"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"b46adaf4-81b9-429f-98f5-482422996c81"},{"name":"Reset Password","event":[{"listen":"test","script":{"id":"17c13cd6-d96c-4fe5-bd9f-480ebe05128f","exec":["postman.setEnvironmentVariable(\"jwt\", JSON.parse(responseBody).token);"],"type":"text/javascript","packages":{}}}],"id":"76011cfe-984e-45f2-bdc9-e7ada270b6f9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PATCH","header":[],"body":{"mode":"raw","raw":"{\n \"password\": \"newpass123\",\n \"passwordConfirm\": \"newpass123\"\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/users/resetPassword/f5653af0de3e639d60c670ca6066cb484157076e23236053b8676adf0b45a31f","description":"Description: Resets the user’s password using the token sent by email.
Auth Required: ❌
Body Parameters:
password: string
passwordConfirm: string
Response: User data with new JWT token
\n","urlObject":{"path":["v1","users","resetPassword","f5653af0de3e639d60c670ca6066cb484157076e23236053b8676adf0b45a31f"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"76011cfe-984e-45f2-bdc9-e7ada270b6f9"},{"name":"Update Current User Password","event":[{"listen":"test","script":{"id":"355ae0c5-782d-456b-80d7-279959fb0f51","exec":["postman.setEnvironmentVariable(\"jwt\", JSON.parse(responseBody).token);"],"type":"text/javascript","packages":{}}}],"id":"d934a599-171a-482f-a88e-e3e980b35386","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"PATCH","header":[],"body":{"mode":"raw","raw":"{\n \"passwordCurrent\": \"newpass123\",\n \"password\": \"password1234\",\n \"passwordConfirm\": \"password1234\"\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/users/updateMyPassword","description":"Description: Updates the password for the currently authenticated user.
Auth Required: ✅ (User)
Body Parameters:
passwordCurrent: string
password: string
passwordConfirm: string
Response: Success message with new token
\n","urlObject":{"path":["v1","users","updateMyPassword"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"d934a599-171a-482f-a88e-e3e980b35386"}],"id":"48fa1ec1-2d9f-458e-a2d0-e8d97e353164","description":"Description:
\n\n\nHandles user authentication and security workflows, including registration, login, password resets, and account protection. JWT-based authentication is implemented with token expiration and refresh support. These routes are public and used to acquire access tokens, reset forgotten passwords, and manage login state.
\n
Key Features:
\nPOST /signup – Register a new user
POST /login – Login and receive JWT token
POST /forgotPassword – Initiate password reset
PATCH /resetPassword/:token – Reset using token
PATCH /updateMyPassword – Authenticated password update