> ## 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/attributes — List Employee Attributes and Their Options

> List the employee attributes released for API use and their options, to filter and group engagement scores by cohort. Planned for Export API v1.4.0.

<Warning>
  Planned for Export API v1.4.0 — not yet available on `api.honestly.com`. Documented here so you can plan your integration. Watch [Versioning](/developers/concepts/versioning) for the release.
</Warning>

Employee attributes are how your organization segments people — Department, Location, Tenure and so on. These two endpoints give you the IDs you pass as `attribute_option_ids` to [`/v1/scores`](/developers/api-reference/scores) and [`/v1/text_responses`](/developers/api-reference/text-responses), so you can narrow results to a cohort.

You need two calls: one to find the attribute, one to find its options.

## Which attributes you can see

An account admin controls which attributes are released for API use, in the Honestly admin interface. `/v1/attributes` returns only released attributes, so anything the lookup shows you is guaranteed to be accepted by `/v1/scores`. Attributes that have not been released are absent from the list and cannot be discovered by guessing IDs.

By default no attribute is released, so nothing becomes queryable through the API until an admin chooses it.

<Warning>
  `/v1/text_responses` accepts **one** of these attributes — a single attribute configured separately in the account settings. This list does not mark which one it is. See [Filtering by attribute](/developers/api-reference/text-responses#one-attribute-only-chosen-in-account-settings) on that endpoint before reusing option IDs across the two.
</Warning>

## List attributes

```
GET https://api.honestly.com/v1/attributes
```

### Query Parameters

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

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

### Example Request

```bash theme={null}
curl -X GET "https://api.honestly.com/v1/attributes" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"
```

### Example Response

```json theme={null}
{
  "total_count": 3,
  "attributes": [
    { "id": 8, "name": "Department" },
    { "id": 9, "name": "Location" },
    { "id": 12, "name": "Tenure" }
  ]
}
```

### Response Fields

<ResponseField name="total_count" type="integer">
  Total number of released attributes, for pagination.
</ResponseField>

<ResponseField name="attributes" type="array">
  <Expandable title="attribute">
    <ResponseField name="id" type="integer">
      Attribute ID. Pass it to `/v1/attributes/{attribute_id}/options` to read the options you can filter by.
    </ResponseField>

    <ResponseField name="name" type="string">
      Attribute name, for example `Department`.
    </ResponseField>
  </Expandable>
</ResponseField>

## List an attribute's options

```
GET https://api.honestly.com/v1/attributes/{attribute_id}/options
```

### Path Parameters

<ParamField path="attribute_id" type="integer" required>
  ID of the attribute, from `/v1/attributes`.
</ParamField>

### Query Parameters

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

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

### Example Request

```bash theme={null}
curl -X GET "https://api.honestly.com/v1/attributes/8/options" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"
```

### Example Response

```json theme={null}
{
  "attribute": { "id": 8, "name": "Department" },
  "total_count": 4,
  "options": [
    { "id": 31, "name": "Engineering" },
    { "id": 32, "name": "Sales" },
    { "id": 33, "name": "Customer Success" },
    { "id": 34, "name": "Legal" }
  ]
}
```

### Response Fields

<ResponseField name="attribute" type="object">
  The attribute these options belong to, with its `id` and `name`.
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of options on this attribute, for pagination.
</ResponseField>

<ResponseField name="options" type="array">
  <Expandable title="option">
    <ResponseField name="id" type="integer">
      Option ID. Pass it as `attribute_option_ids` to [`/v1/scores`](/developers/api-reference/scores), or to [`/v1/text_responses`](/developers/api-reference/text-responses) when this is the account's configured text-response attribute.
    </ResponseField>

    <ResponseField name="name" type="string">
      Option name, for example `Engineering`.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Requesting the options of an attribute that has not been released for API use returns `404`, the same as an attribute that does not exist. The API never reveals that a blocked attribute exists.
</Note>

## Putting it together

```bash theme={null}
# 1. Find the attributes
curl -X GET "https://api.honestly.com/v1/attributes" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"
# Department is 8, Location is 9

# 2. Find the option IDs
curl -X GET "https://api.honestly.com/v1/attributes/8/options" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"
# Engineering is 31

# 3. Filter a score to that cohort
curl -G "https://api.honestly.com/v1/scores" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY" \
  --data-urlencode "question_ids=121" \
  --data-urlencode "period_from=2026-01-01T00:00:00Z" \
  --data-urlencode "period_to=2026-03-31T23:59:59Z" \
  --data-urlencode "attribute_option_ids=31"
```

See [Filtering by attribute](/developers/api-reference/scores#filtering-by-attribute) for how options combine, and for how to build a heatmap by calling `/v1/scores` once per cell.