Skip to main content
GET
/
user
/
list
/
{start}
/
{end}
Get list of users with pagination
curl --request GET \
  --url http://localhost:2000/user/list/{start}/{end} \
  --header 'Authorization: Bearer <token>'
{
  "message": "<string>",
  "data": {
    "total": 25,
    "users": [
      {
        "emails": [
          "[email protected]"
        ],
        "personalInformation": {
          "firstName": "John",
          "lastName": "Doe"
        },
        "role": "employee",
        "department": {
          "id": "64ef3c29f9a1c27e1b2c3a4d",
          "role": "manager"
        },
        "reportsTo": "64ef3c29f9a1c27e1b2c3a99",
        "createdAt": "2025-09-12T08:30:00Z",
        "config": {
          "lastActive": "2025-09-12T09:15:00Z"
        },
        "linkedAccounts": {
          "google": {
            "meta": {
              "email": "zain"
            }
          }
        }
      }
    ]
  }
}
Admin-only endpoint to retrieve a list of users with pagination support.

​
Request

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesBearer token

​
Path Parameters

ParameterTypeRequiredDescription
startintegerYesStarting index (0 for beginning)
endintegerYesEnding index (0 to return all users)

​
Query Parameters

ParameterTypeRequiredDescription
departmentFilterstringNoDepartment ID to filter users by

​
departmentFilter Details

  • Must be a valid MongoDB ObjectId of a department
  • Can be null to return all users that are not part of any department
  • Example: "64ef3c29f9a1c27e1b2c3a4d"

​
Response

​
200 OK - Successfully retrieved user list

{
  "message": "Users retrieved successfully",
  "data": {
    "total": 25,
    "users": [
      {
        "_id": "64b7f1a2e4b0a5d3f9c12345",
        "emails": "[email protected]",
        "firstName": "John",
        "lastName": "Doe",
        "role": "user",
        "department": {
          "_id": "64b7f2b3e4b0a5d3f9c54321",
          "name": "Customer Support"
        },
        "rcExtension": "1234",
        "phone": "+1-555-555-5555"
      }
    ]
  }
}

​
401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid token or insufficient permissions"
  }
}

​
500 Internal Server Error

{
  "error": {
    "code": "SERVER_ERROR",
    "message": "Internal server error"
  }
}

​
Examples

​
Get first 10 users

curl -X GET 'http://localhost:2000/user/list/0/10' \
  -H 'Authorization: Bearer your-jwt-token'

​
Get all users

curl -X GET 'http://localhost:2000/user/list/0/0' \
  -H 'Authorization: Bearer your-jwt-token'

​
Get users from specific department

curl -X GET 'http://localhost:2000/user/list/0/10?departmentFilter=64ef3c29f9a1c27e1b2c3a4d' \
  -H 'Authorization: Bearer your-jwt-token'

​
Get users without department

curl -X GET 'http://localhost:2000/user/list/0/10?departmentFilter=null' \
  -H 'Authorization: Bearer your-jwt-token'

​
Notes

  • This is an admin-only endpoint - requires administrative privileges
  • Pagination is zero-based (start at 0)
  • Setting both start and end to 0 returns all users
  • The response includes a total count for pagination controls
  • Users are returned with summary information, not full profile data
  • Use departmentFilter to narrow down results by department

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
start
integer
required

Starting index (0 for beginning)

Required range: x >= 0
​
end
integer
required

Ending index (0 to return all users)

Required range: x >= 0

Query Parameters

​
departmentFilter
string | null

Department ID to filter users by. - Must be a valid MongoDB ObjectId of a department. - Can be null to return all users that is not a part of any department.

Response

Successfully retrieved user list

​
message
string
​
data
object