Surveys
Engagement, pulse, onboarding and exit surveys as the app runs them: built from a template, opened to an audience, closed by HR or at their closing time. The results route returns what the app shows HR and nothing more: counts, means, eNPS and the department heat-map above minimum_group_size. An individual answer is never a resource and never in an event.
Available on plans that include surveys.
These endpoints need a plan that includes Surveys (surveys). On a plan without it, requests return 402 with code: plan_upgrade_required and feature naming what an upgrade would add.
List surveys
/v1/surveysQuery parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Page size. Values above 100 are clamped. |
starting_after | string | No | Opaque cursor from a previous response’s next_cursor. |
updated_since | timestamp | No | Return records changed at or after this instant. Tracks the record itself, not its child collections. |
status | draft · open · closed | No | Only surveys in this state. |
kind | string (enum) | No | Only surveys of this kind. |
Responses
| Status | Meaning |
|---|---|
200 | A page of surveys. |
401 | The API key is missing, malformed, revoked or expired. |
402 | The workspace's plan does not include Surveys (plan_upgrade_required). |
403 | The key does not carry the required scopes. |
429 | Rate limit exceeded. See the RateLimit-* headers. |
Retrieve a survey
/v1/surveys/{id}Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The identifier returned as id on the object. |
Responses
| Status | Meaning |
|---|---|
200 | The survey. |
401 | The API key is missing, malformed, revoked or expired. |
402 | The workspace's plan does not include Surveys (plan_upgrade_required). |
403 | The key does not carry the required scopes. |
404 | No such survey in this workspace. |
429 | Rate limit exceeded. See the RateLimit-* headers. |
Retrieve the results of a survey
/v1/surveys/{id}/resultsThe aggregates the app shows: how many were invited and answered, and per question the mean and distribution of a scale, the eNPS of an nps question, the counts per option of a choice, and the texts of an open question. departments is the department heat-map. No route returns an individual answer.
An anonymous survey is read by these rules, the same ones the app applies:
- While it is open the response carries
invited,respondedandresponse_rateonly:hiddenistrue,hidden_reasonisopen, andquestionsanddepartmentsare empty. Results exist once the survey has closed. - Closed with fewer than
minimum_group_sizeresponses: the same, withhidden_reasonbelow_floor.minimum_group_sizeis never under 3. departmentsholds complete groups only: each row has at leastminimum_group_sizeresponses, departments under it are folded into one row with a nulldepartment_id(together with the smallest department otherwise shown, when the fold alone would be under the floor), and the rows add up toinvitedandresponded. When no department can be shown on its own the list is empty.- A question answered by fewer than
minimum_group_sizepeople hassuppressed: trueand null figures; a heat-map cell resting on fewer answers than that is null. textsare for the survey as a whole, in an order made from the texts alone.
A survey answered by name returns its results while open, with every question in full and texts in alphabetical order.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The identifier returned as id on the object. |
Responses
| Status | Meaning |
|---|---|
200 | The results. |
401 | The API key is missing, malformed, revoked or expired. |
402 | The workspace's plan does not include Surveys (plan_upgrade_required). |
403 | The key does not carry the required scopes. |
429 | Rate limit exceeded. See the RateLimit-* headers. |