List Employees

Retrieve a paginated list of employees with optional expansions for related data.

Note: This endpoint consolidates the previous /api/v1/users and /api/v1/employees endpoints. Those endpoints are deprecated and will be removed in a future version. Please migrate to this unified endpoint.

GET

/api/v2/employees

Description

The List Employees endpoint returns a paginated list of all employees in your organization. You can filter results by email and optionally expand related data such as assigned assets, manager information, and department details using the include query parameter.

Each page contains up to 10 records by default. Use the pagination metadata in the response to navigate through multiple pages.

Request

Headers

Header	Value	Required
Authorization	Bearer <access_token>	Yes
Content-Type	application/json	Yes

Query Parameters

Parameter	Type	Required	Description
page	Number	No	Specifies the page number for pagination. Default is 1.
email	String	No	Filter employees by email address. Returns only matching employees.
include	String	No	Comma-separated list of related data to include. Options: `assets`, `manager`, `department`. Example: `assets,manager`

Response Fields

Field	Type	Description
id	String	Unique employee identifier
email	String	Employee's email address
firstName	String	Employee's first name
lastName	String	Employee's last name
phone	String	Phone number
phoneCountryCode	String	Country code for phone number (e.g., "US")
status	String	Employment status: `active`, `inactive`, or `on_leave`
startDate	String	Employee's start date (ISO 8601 format)
country	String	Country code (ISO 3166-1 alpha-2)
state	String	State or province
city	String	City name
zip	String	Zip or postal code
address1	String	Primary address line
address2	String	Secondary address line (suite, apt, etc.)
locationType	String	Type of location: Warehouse, Corporate Office, Retail Store, or Remote Employee
locationName	String \| null	Name of associated location (if applicable)
assignedAssets	Array	(Only with `include=assets`) Array of assigned assets. Empty if no assets assigned.
department	String	(Only with `include=department`) Employee's department
jobTitle	String	(Only with `include=department`) Employee's job title
manager	Object	(Only with `include=manager`) Manager details with id, name, and email
createdAt	String	Timestamp when record was created (ISO 8601)
updatedAt	String	Timestamp of last update (ISO 8601)

Error Responses

Common error responses you may encounter when using this endpoint.

Notes

Authentication is required for all requests. Include your access token in the Authorization header.
The default page size is 10 records. Use the pagination metadata to navigate through multiple pages.
The include parameter accepts comma-separated values. You can combine multiple expansions (e.g., ?include=assets,manager,department).
The assignedAssets array will be empty if the employee has no assigned assets. Check the array length before accessing asset data.
Access is restricted to employees within your organization. Insufficient permissions will result in a 403 error.
For retrieving a single employee with full details, use the Get Employee by ID endpoint instead.

Request: Basic List

curl -X GET https://api.unduit.com/v2/employees?page=1 \
  -H "Authorization: Bearer <token>"

Request: Filter by Email

curl -X GET https://api.unduit.com/v2/employees?page=1&email=jane.smith%40example.com \
  -H "Authorization: Bearer <token>"

Request: Include Assets

curl -X GET https://api.unduit.com/v2/employees?page=1&include=assets \
  -H "Authorization: Bearer <token>"

Request: Full Expansion

curl -X GET https://api.unduit.com/v2/employees?page=1&include=assets%2Cmanager%2Cdepartment \
  -H "Authorization: Bearer <token>"

Success Response (200) - Base

{
  "success": true,
  "data": {
    "employees": [
      {
        "id": "emp_1234567890",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "phone": "1234567890",
        "phoneCountryCode": "US",
        "status": "active",
        "startDate": "2023-01-15",
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "zip": "90001",
        "address1": "1234 Elm Street",
        "address2": "",
        "locationType": "Remote Employee",
        "locationName": null,
        "createdAt": "2023-01-10T08:00:00Z",
        "updatedAt": "2024-06-15T14:30:00Z"
      },
      {
        "id": "emp_0987654321",
        "email": "jane.smith@example.com",
        "firstName": "Jane",
        "lastName": "Smith",
        "phone": "0987654321",
        "phoneCountryCode": "US",
        "status": "active",
        "startDate": "2022-08-20",
        "country": "US",
        "state": "NY",
        "city": "New York",
        "zip": "10001",
        "address1": "5678 Oak Avenue",
        "address2": "Unit 202",
        "locationType": "Remote Employee",
        "locationName": null,
        "createdAt": "2022-08-15T09:00:00Z",
        "updatedAt": "2024-05-20T11:45:00Z"
      }
    ],
    "pagination": {
      "total": 465,
      "totalPages": 47,
      "currentPage": 1,
      "perPage": 10
    }
  }
}

Success Response (200) - With Assets

{
  "success": true,
  "data": {
    "employees": [
      {
        "id": "emp_1234567890",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "phone": "1234567890",
        "phoneCountryCode": "US",
        "status": "active",
        "startDate": "2023-01-15",
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "zip": "90001",
        "address1": "1234 Elm Street",
        "address2": "",
        "locationType": "Remote Employee",
        "locationName": null,
        "assignedAssets": [],
        "createdAt": "2023-01-10T08:00:00Z",
        "updatedAt": "2024-06-15T14:30:00Z"
      },
      {
        "id": "emp_0987654321",
        "email": "jane.smith@example.com",
        "firstName": "Jane",
        "lastName": "Smith",
        "phone": "0987654321",
        "phoneCountryCode": "US",
        "status": "active",
        "startDate": "2022-08-20",
        "country": "US",
        "state": "NY",
        "city": "New York",
        "zip": "10001",
        "address1": "5678 Oak Avenue",
        "address2": "Unit 202",
        "locationType": "Remote Employee",
        "locationName": null,
        "assignedAssets": [
          {
            "assetId": "LEN-0000-ABCD1234",
            "modelName": "Demo Laptop",
            "modelNumber": "DL-1234",
            "productType": "Laptop",
            "purchaseDate": "2024-10-31",
            "serialNumber": "SN-ABCD1234",
            "imei": "",
            "imei2": "",
            "sku": "",
            "assetStatus": "In Use"
          }
        ],
        "createdAt": "2022-08-15T09:00:00Z",
        "updatedAt": "2024-05-20T11:45:00Z"
      }
    ],
    "pagination": {
      "total": 465,
      "totalPages": 47,
      "currentPage": 1,
      "perPage": 10
    }
  }
}

Success Response (200) - With Manager & Department

{
  "success": true,
  "data": {
    "employees": [
      {
        "id": "emp_1234567890",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "phone": "1234567890",
        "phoneCountryCode": "US",
        "status": "active",
        "startDate": "2023-01-15",
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "zip": "90001",
        "address1": "1234 Elm Street",
        "address2": "",
        "locationType": "Remote Employee",
        "locationName": null,
        "department": "Engineering",
        "jobTitle": "Senior Software Engineer",
        "manager": {
          "id": "emp_1111111111",
          "name": "Sarah Johnson",
          "email": "sarah.johnson@example.com"
        },
        "createdAt": "2023-01-10T08:00:00Z",
        "updatedAt": "2024-06-15T14:30:00Z"
      }
    ],
    "pagination": {
      "total": 465,
      "totalPages": 47,
      "currentPage": 1,
      "perPage": 10
    }
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid authentication token"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to access employee data"
  }
}