Skip to main content
The Honestly Export API follows semantic versioning and is designed to be backward-compatible whenever possible, so your integrations keep working as the API evolves.

​
Current version

The current version of the Honestly Export API is v1.3.0.

​
Versioning scheme

Version numbers follow the MAJOR.MINOR.PATCH format. Each component signals a different type of change:
  • MAJOR — Incremented for breaking changes. All API consumers are notified and coordinated with in advance before a major version is released.
  • MINOR — Incremented when new functionality is added in a backward-compatible way, such as new endpoints or new optional response fields.
  • PATCH — Incremented for backward-compatible bug fixes or editorial changes that do not affect functionality.

​
Backward compatibility guarantees

When Honestly increments a MINOR or PATCH version, the following guarantees apply:
  • New response fields are always optional. Adding a field to a response will never break existing consumers that don’t expect it.
  • Field semantics never change. A field that represents a customer number will always represent a customer number — its meaning is stable across versions.
  • Validation rules on input fields are never made more restrictive. A request that was valid before a patch or minor release will remain valid after it.
  • Enum output values use x-extensible-enum. New enum values may be introduced over time. Your code should handle unknown enum values gracefully rather than failing.
  • URLs that must change will use 301 redirects. If an endpoint path is moved, Honestly will issue a permanent redirect so existing integrations continue to function.

​
Changelog

Not yet available on api.honestly.com. Documented in advance so you can plan your integration.Add attributes, survey_cycles and text_responses endpoints. Extend the scores endpoint with survey_ids and attribute_option_ids parameters, with responses and answers counts, and with a score distribution and per-cycle participation block that are always returned. Return a topics array on each text response carrying the assigned topics and their per-topic sentiment. Add a dimension field to the questions endpoint. The surveys endpoint is unchanged.The score distribution reports one count per scale_point rather than banding answers into ranges. Every point the requested questions can produce is listed, including those nobody chose, so the array is a direct picture of the answer scale. Points are normalized to 0–100, except for eNPS, which reports the raw 0–10 answer points. The field is named scale_point rather than score because the aggregate score runs -100–100 on the eNPS scale.text_responses scopes answers with survey_ids and survey_cycle_ids, both optional, and has no date-range parameter. A caller-chosen date range would let the submission date of an individual answer be recovered by comparing two overlapping requests, which is one of the strongest ways to identify an author; whole cycles, already anonymity-checked, do not.text_responses also filters by a single employee attribute, configured per account in the account settings, with multiple options of that attribute allowed. scores continues to accept options across several attributes.Add POST /v1/employees/imports for pushing your full employee list, replacing CSV over SFTP. It is the first write endpoint in the API, and it does not use the read key: API keys now carry scopes, and this endpoint requires a key with employees:write that the REST API integration issues for itself. Keys issued before scopes existed keep the read access they had.One change is not backward-compatible in the strict sense: respondents becomes null on a suppressed score, where it currently returns the real cohort size. The cohort size is itself identifying, so withholding it is a privacy fix. Integrations reading that value should tolerate null before this release ships.
Add initiatives endpoint to retrieve the account’s initiatives (action items) as a paginated list with all of their data.
Add scores endpoint to retrieve a single aggregated, anonymity-protected score for a set of questions over a time window.
Add roles Report viewer and Respondee to the employee endpoint.
Add is_deleted property to the employees list at the employees endpoint.
Add is_deleted property to the questions list at the questions endpoint.
Add is_archived parameter to the surveys endpoint.
Add current_survey_ends_at property to the surveys list.
Add next_survey_starts_at property to the surveys list.
Endpoint survey_assignments: add survey_id property. Add versioning and backwards compatibility information. Change properties of type enum to x-extensible-enum. Add is_deactivated property to the surveys endpoint.
Initial release.
If you have concerns about an upcoming breaking change, contact service@honestly.com — all major version changes are coordinated with API consumers in advance.