GET /v1/attributes — List Employee Attributes and Their Options

Planned for Export API v1.4.0 — not yet available on api.honestly.com. Documented here so you can plan your integration. Watch Versioning for the release.

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 and /v1/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.

/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 on that endpoint before reusing option IDs across the two.

List attributes

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

Query Parameters

integer

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

integer

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

Example Request

curl -X GET "https://api.honestly.com/v1/attributes" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"

Example Response

{
  "total_count": 3,
  "attributes": [
    { "id": 8, "name": "Department" },
    { "id": 9, "name": "Location" },
    { "id": 12, "name": "Tenure" }
  ]
}

Response Fields

integer

Total number of released attributes, for pagination.

array

Show attribute

integer

Attribute ID. Pass it to /v1/attributes/{attribute_id}/options to read the options you can filter by.

string

Attribute name, for example Department.

List an attribute’s options

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

Path Parameters

integer

required

ID of the attribute, from /v1/attributes.

Query Parameters

integer

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

integer

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

Example Request

curl -X GET "https://api.honestly.com/v1/attributes/8/options" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"

Example Response

{
  "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

object

The attribute these options belong to, with its id and name.

integer

Total number of options on this attribute, for pagination.

array

Show option

integer

Option ID. Pass it as attribute_option_ids to /v1/scores, or to /v1/text_responses when this is the account’s configured text-response attribute.

string

Option name, for example Engineering.

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.

Putting it together

# 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 for how options combine, and for how to build a heatmap by calling /v1/scores once per cell.

​Which attributes you can see

​List attributes

​Query Parameters

​Example Request

​Example Response

​Response Fields

​List an attribute’s options

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Putting it together

Which attributes you can see

List attributes

Query Parameters

Example Request

Example Response

Response Fields

List an attribute’s options

Path Parameters

Query Parameters

Example Request

Example Response

Response Fields

Putting it together