GET /v1/employees — Export and List Employee Records

The /v1/employees endpoint returns a paginated list of all employee records in your Honestly account. Use it to enrich survey response exports with employee metadata for analysis and segmentation.

Endpoint

GET https://api.honestly.com/v1/employees

Query Parameters

integer

Maximum number of employees to return per page. Accepts values from 0 to 1000. Defaults to 100.

integer

Number of employees to skip before returning results. Defaults to 0.

Example Request

curl -X GET "https://api.honestly.com/v1/employees?limit=200&offset=0" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"

Example Response

{
  "total_count": 2,
  "employees": [
    {
      "id": 1,
      "import_id": "x234b",
      "email": "alice@example.com",
      "firstname": "Alice",
      "lastname": "Johnson",
      "role": "Manager",
      "is_deleted": false,
      "attributes": [
        {
          "id": 5,
          "name": "Department",
          "attribute_values": [
            { "id": 9, "name": "Customer Success" }
          ]
        }
      ]
    },
    {
      "id": 2,
      "import_id": null,
      "email": "carol@example.com",
      "firstname": "Carol",
      "lastname": "Lee",
      "role": "Report viewer",
      "is_deleted": true,
      "attributes": []
    }
  ]
}

Response Fields

integer

The total number of employee records in your account, across all pages.

array

A paginated list of employee objects.

Show employee object fields

integer

Unique identifier for the employee.

string | null

The identifier assigned when the employee was created through the Honestly Import API. null when the employee was created in the web application.

string

The employee’s email address.

string | null

The employee’s first name.

string | null

The employee’s last name.

string | null

The employee’s permission role within Honestly. The default roles are Admin, Manager, Analyst, Employee, Report viewer, and Respondee. Uses an extensible enum, and may be null.

boolean

true if the employee has been removed from the account.

array

Customer-defined attributes used to segment employees.

Show attribute fields

integer

Unique identifier for the attribute.

string

The attribute name (e.g. Department).

array

The values assigned to this employee for the attribute, each with an id (integer) and name (string).

The role field uses an extensible enum. New roles may be added in future API versions. Ensure your pipeline handles unknown role values without failing.

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Response Fields

Endpoint

Query Parameters

Example Request

Example Response

Response Fields