> ## Documentation Index
> Fetch the complete documentation index at: https://help.honestly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/employees — Export and List Employee Records

> Retrieve all employee records from your Honestly account, including roles, custom attributes, and deleted status. Cross-reference with your response exports.

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

<ParamField query="limit" type="integer">
  Maximum number of employees to return per page. Accepts values from `0` to `1000`. Defaults to `100`.
</ParamField>

<ParamField query="offset" type="integer">
  Number of employees to skip before returning results. Defaults to `0`.
</ParamField>

## Example Request

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

## Example Response

```json theme={null}
{
  "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

<ResponseField name="total_count" type="integer">
  The total number of employee records in your account, across all pages.
</ResponseField>

<ResponseField name="employees" type="array">
  A paginated list of employee objects.

  <Expandable title="employee object fields">
    <ResponseField name="id" type="integer">
      Unique identifier for the employee.
    </ResponseField>

    <ResponseField name="import_id" type="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.
    </ResponseField>

    <ResponseField name="email" type="string">
      The employee's email address.
    </ResponseField>

    <ResponseField name="firstname" type="string | null">
      The employee's first name.
    </ResponseField>

    <ResponseField name="lastname" type="string | null">
      The employee's last name.
    </ResponseField>

    <ResponseField name="role" type="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`.
    </ResponseField>

    <ResponseField name="is_deleted" type="boolean">
      `true` if the employee has been removed from the account.
    </ResponseField>

    <ResponseField name="attributes" type="array">
      Customer-defined attributes used to segment employees.

      <Expandable title="attribute fields">
        <ResponseField name="id" type="integer">
          Unique identifier for the attribute.
        </ResponseField>

        <ResponseField name="name" type="string">
          The attribute name (e.g. `Department`).
        </ResponseField>

        <ResponseField name="attribute_values" type="array">
          The values assigned to this employee for the attribute, each with an `id` (integer) and `name` (string).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  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.
</Note>