Employees List

Retrieve a paginated list of employee records with their contact details, addresses, and assigned assets.

GET

/api/v1/employees

Description

Returns a paginated list of employee records for your company, including work contact details, address, and department information. Employment data and assigned assets can be included per employee on request.

Request

Headers

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

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number to retrieve. Defaults to 1.
limit	number	No	Number of records per page. Defaults to 10, maximum 100.
email	string	No	Filter results by work email address.
include_assets	boolean	No	Set to true or 1 to include a list of assets assigned to each employee.

Response

Pagination Fields

Field	Type	Description
success	boolean	Whether the request was successful.
totalUsers	number	Total number of matching employee records.
totalPages	number	Total number of pages available.
currentPage	number	The page number returned.
per_page	number	Number of records per page.
users	array	List of employee records.

Employee Fields

Field	Type	Description
users[].id	string	Use the full value in detail and update routes.
users[].FirstName	string	Employee's first name.
users[].LastName	string	Employee's last name.
users[].WorkEmail	string	Employee's work email address.
users[].PersonalEmail	string	Employee's personal email address.
users[].WorkPhone	string	Work phone number, digits only, excluding country code (e.g. 4155551234).
users[].WorkPhoneCountry	string	Work phone country as an ISO 3166-1 alpha-2 code (e.g. US, GB).
users[].PersonalPhone	string	Personal phone number, digits only, excluding country code.
users[].PersonalPhoneCountry	string	Personal phone country as an ISO 3166-1 alpha-2 code.
users[].ContactInfo	string	Legacy alias for WorkPhone.
users[].PhoneCountryCode	string	Legacy alias for WorkPhoneCountry.
users[].Address_1	string	Address line 1.
users[].Address_2	string	Address line 2. Null if not provided.
users[].City	string	City.
users[].State	string	State or province.
users[].Zip	string	Postal or zip code.
users[].Country	string	Country as an ISO 3166-1 alpha-2 code (e.g. US, DE).
users[].LocationType	string	How the employee is based. Known values: Corporate Office, Remote Employee, Retail Store. Treat as case-insensitive.
users[].LocationName	string	Display name for the employee's location (e.g. Remote - San Francisco, New York HQ).
users[].Department	string	Department the employee belongs to.
users[].EmployeeId	string	Employee ID on their location record. May differ from EmploymentInformation.employee_number_id.
users[].ConfigureCostCenterId	number	ID of the assigned cost center. Null if not configured.
users[].Source	string	Origin of the record. unduit for records managed in Unduit, google for records synced from Google Workspace.
users[].EmploymentInformation	object	Employment details synced from a connected HR system. Null if unavailable. When present, only populated fields are included. See fields below.
users[].AssignedAssets	array	Assigned assets per employee. Only included when include_assets=true. Returns [] if no assets are assigned.

EmploymentInformation Fields

Field	Type	Description
users[].EmploymentInformation.employee_number_id	string	Employee number in the HR system. May differ from top-level EmployeeId.
users[].EmploymentInformation.employment_status	string	Employment status (e.g. Active, Terminated).
users[].EmploymentInformation.employment_type	string	Employment type (e.g. Full Time, Part Time, Contractor).
users[].EmploymentInformation.employment_start_date	string	Start date in YYYY-MM-DD format.
users[].EmploymentInformation.termination_date	string	Termination date in YYYY-MM-DD format. Only present when employment_status is Terminated.
users[].EmploymentInformation.work_phone	string	Work phone from the HR system, digits only. May differ from top-level WorkPhone.
users[].EmploymentInformation.manager	string	Employee's direct manager name or identifier.
users[].EmploymentInformation.personal_email	string	Personal email as stored in the HR system.
users[].EmploymentInformation.personal_phone	string	Personal phone from the HR system, digits only.
users[].EmploymentInformation.personal_contact_country	string	Personal phone country as an ISO 3166-1 alpha-2 code.

AssignedAssets Fields

Field	Type	Description
users[].AssignedAssets[].assetId	string	Asset ID as set by your organization.
users[].AssignedAssets[].serialNumber	string	Device serial number.
users[].AssignedAssets[].modelName	string	Product or model name (e.g. MacBook Pro 14).
users[].AssignedAssets[].modelNumber	string	Manufacturer model number (e.g. A2338).
users[].AssignedAssets[].productType	string	Device category (e.g. Laptop, Phone).
users[].AssignedAssets[].purchaseDate	string	Purchase date in YYYY-MM-DD format.
users[].AssignedAssets[].imei	string	Primary IMEI. Empty string if not applicable.
users[].AssignedAssets[].imei2	string	Secondary IMEI. Empty string if not applicable.
users[].AssignedAssets[].sku	string	Asset SKU.
users[].AssignedAssets[].assetStatus	string	Current asset status (e.g. In Use, In Storage).

Notes

The default page size is 10. Use the limit parameter to increase this, up to a maximum of 100.
Employee id values are opaque strings (`{7-digit-prefix}-{numericId}`). Pass the full value to GET /api/v1/employees/{id} and update routes.
Email, ContactInfo and PhoneCountryCode are legacy field aliases retained for backwards compatibility. Use WorkEmail, WorkPhone and WorkPhoneCountry respectively in all new integrations.
EmploymentInformation is null when no HR system is connected or no data exists for the employee. When present, only fields that contain a value are included — fields with no data are omitted rather than returned as null.
termination_date inside EmploymentInformation is only present when employment_status is Terminated.
AssignedAssets is only included in the response when include_assets=true or include_assets=1 is passed as a query parameter. When included, an empty array [] is returned for employees with no assigned assets.
LocationType values are returned as stored and may vary in casing (e.g. Corporate Office and corporate office refer to the same type). Treat this field as case-insensitive when comparing values.
Source indicates the origin of the employee record. Records created or managed directly in Unduit return unduit. Records synced from Google Workspace return google.
PersonalPhone and PersonalEmail at the top level reflect what was entered directly in Unduit. The equivalent fields inside EmploymentInformation reflect what was synced from the connected HR system and may differ.

Related Endpoints

Employee Detail

Retrieve a single employee

Add Employee

Add a new employee

Departments List

List configured departments

Did this page help you?

Request

curl -X GET https://uat.unduit.com/api-exposed/api/v1/employees?page=1&limit=10&include_assets=true \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Success Response

{
  "success": true,
  "totalUsers": 2,
  "totalPages": 1,
  "currentPage": 1,
  "per_page": 10,
  "users": [
    {
      "id": "1421797-501",
      "FirstName": "Jane",
      "LastName": "Doe",
      "WorkEmail": "jane.doe@company.com",
      "PersonalEmail": "jane.doe@gmail.com",
      "WorkPhone": "4155551234",
      "WorkPhoneCountry": "US",
      "PersonalPhone": "4155559999",
      "PersonalPhoneCountry": "US",
      "ContactInfo": "4155551234",
      "PhoneCountryCode": "US",
      "Address_1": "123 Market Street",
      "Address_2": "Suite 400",
      "City": "San Francisco",
      "State": "CA",
      "Zip": "94103",
      "Country": "US",
      "LocationType": "Remote Employee",
      "LocationName": "Remote - San Francisco",
      "Department": "IT",
      "EmployeeId": "EMP-501",
      "ConfigureCostCenterId": 42,
      "Source": "unduit",
      "EmploymentInformation": {
        "employee_number_id": "HR-501",
        "employment_status": "Active",
        "employment_type": "Full Time",
        "employment_start_date": "2024-01-15",
        "work_phone": "4155551234",
        "manager": "John Manager",
        "personal_email": "jane.doe@gmail.com",
        "personal_phone": "4155559999",
        "personal_contact_country": "US"
      },
      "AssignedAssets": [
        {
          "assetId": "AST-1001",
          "serialNumber": "C02XK1ABCDEF",
          "modelName": "MacBook Pro 14",
          "modelNumber": "A2338",
          "productType": "Laptop",
          "purchaseDate": "2024-01-15",
          "imei": "",
          "imei2": "",
          "sku": "MBP-14-2024",
          "assetStatus": "In Use"
        }
      ]
    },
    {
      "id": "7890262-502",
      "FirstName": "Alex",
      "LastName": "Johnson",
      "WorkEmail": "alex.johnson@company.com",
      "Email": "alex.johnson@company.com",
      "PersonalEmail": "alex.j@gmail.com",
      "WorkPhone": "2125550100",
      "WorkPhoneCountry": "US",
      "PersonalPhone": null,
      "PersonalPhoneCountry": null,
      "ContactInfo": "2125550100",
      "PhoneCountryCode": "US",
      "Address_1": "350 Fifth Avenue",
      "Address_2": null,
      "City": "New York",
      "State": "NY",
      "Zip": "10118",
      "Country": "US",
      "LocationType": "Corporate Office",
      "LocationName": "New York HQ",
      "Department": "Finance",
      "EmployeeId": "EMP-502",
      "ConfigureCostCenterId": null,
      "CostCenter": null,
      "Source": "google",
      "EmploymentInformation": null,
      "AssignedAssets": []
    }
  ]
}