Skip to main content

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.

Plan feature

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​

GET/v1/surveys

Query parameters​

NameTypeRequiredDescription
limitintegerNoPage size. Values above 100 are clamped.
starting_afterstringNoOpaque cursor from a previous response’s next_cursor.
updated_sincetimestampNoReturn records changed at or after this instant. Tracks the record itself, not its child collections.
statusdraft · open · closedNoOnly surveys in this state.
kindstring (enum)NoOnly surveys of this kind.

Responses​

StatusMeaning
200A page of surveys.
401The API key is missing, malformed, revoked or expired.
402The workspace's plan does not include Surveys (plan_upgrade_required).
403The key does not carry the required scopes.
429Rate limit exceeded. See the RateLimit-* headers.

Retrieve a survey​

GET/v1/surveys/{id}

Path parameters​

NameTypeRequiredDescription
idstringYesThe identifier returned as id on the object.

Responses​

StatusMeaning
200The survey.
401The API key is missing, malformed, revoked or expired.
402The workspace's plan does not include Surveys (plan_upgrade_required).
403The key does not carry the required scopes.
404No such survey in this workspace.
429Rate limit exceeded. See the RateLimit-* headers.

Retrieve the results of a survey​

GET/v1/surveys/{id}/results

The 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, responded and response_rate only: hidden is true, hidden_reason is open, and questions and departments are empty. Results exist once the survey has closed.
  • Closed with fewer than minimum_group_size responses: the same, with hidden_reason below_floor. minimum_group_size is never under 3.
  • departments holds complete groups only: each row has at least minimum_group_size responses, departments under it are folded into one row with a null department_id (together with the smallest department otherwise shown, when the fold alone would be under the floor), and the rows add up to invited and responded. When no department can be shown on its own the list is empty.
  • A question answered by fewer than minimum_group_size people has suppressed: true and null figures; a heat-map cell resting on fewer answers than that is null.
  • texts are 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​

NameTypeRequiredDescription
idstringYesThe identifier returned as id on the object.

Responses​

StatusMeaning
200The results.
401The API key is missing, malformed, revoked or expired.
402The workspace's plan does not include Surveys (plan_upgrade_required).
403The key does not carry the required scopes.
429Rate limit exceeded. See the RateLimit-* headers.