GET /v1/questions — List and Filter Survey Questions

The /v1/questions endpoint returns a paginated list of every question stored in your Honestly account. Use it to look up question IDs, texts, types and answer options before you request scores. The list is account-wide and is not a picture of your current surveys: it contains more than your active surveys ask, and the same question text can appear under many IDs. Read What the list contains and Question IDs and surveys before you build a data model on top of it.

Endpoint

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

Query Parameters

integer

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

integer

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

Example Request

curl -X GET "https://api.honestly.com/v1/questions?limit=100&offset=0" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"

Example Response

{
  "total_count": 2,
  "questions": [
    {
      "id": 23,
      "name": {
        "en": "How satisfied are you with your workplace?",
        "de": "Sind Sie zufrieden mit Ihrem Arbeitsplatz?"
      },
      "type": "ranked_select",
      "is_deleted": false,
      "dimension": "Leadership",
      "answer_options": [
        {
          "id": 12,
          "name": { "en": "Not satisfied at all", "de": "Gar nicht zufrieden" },
          "value": 0,
          "is_maximum": false,
          "is_minimum": true
        },
        {
          "id": 13,
          "name": { "en": "Very satisfied", "de": "Sehr zufrieden" },
          "value": 5,
          "is_maximum": true,
          "is_minimum": false
        }
      ]
    },
    {
      "id": 24,
      "name": {
        "en": "What could we improve about our meetings?",
        "de": "Was können wir an unseren Meetings verbessern?"
      },
      "type": "textfield",
      "is_deleted": true,
      "dimension": null,
      "answer_options": []
    }
  ]
}

Response Fields

integer

Total number of questions matching the query.

array

List of question objects.

Show question object fields

integer

Unique identifier for the question. An ID belongs to exactly one questionnaire, so the same question text can appear under several IDs — see Question IDs and surveys.

object

The translated question text, keyed by ISO 639-1 language code (e.g. { "en": "…", "de": "…" }).

string

The question type. One of stars, textfield, single_select, multiple_select, ranked_select, smiley_faces, or nps. Use the type to determine how to calculate a score.

boolean

true if the question has been deleted from its questionnaire. Deleted questions stay in the list, so filter on this field if you only want questions that are still asked.

string | null

Planned for v1.4.0. Title of the dimension this question belongs to, for example "Leadership". null when the question is not mapped to a dimension.A question belongs to at most one dimension, so this is a plain string rather than an object or a list. Group questions by matching on this value.

array

Always present. For question types with a fixed set of options (single_select, multiple_select, ranked_select, smiley_faces, nps, stars) it lists every possible option; for free-text questions (textfield) it is an empty array.

Show answer option fields

integer

Unique identifier for the answer option.

object

The translated option label, keyed by ISO 639-1 language code.

number

Numeric value that can be used to calculate a score.

boolean

true when this option is the best possible answer in the ordered set.

boolean

true when this option is the worst possible answer in the ordered set.

The type field uses an extensible enum — new question types may be added as Honestly introduces new features. Make sure your code handles unknown values gracefully.

The dimension field is planned for v1.4.0 and is not yet returned by api.honestly.com. It is documented here so you can plan your integration. Watch Versioning for the release.

To score a whole dimension, collect the IDs of every question whose dimension matches that title and pass them together as question_ids to /v1/scores — the endpoint aggregates them into one score.

What the list contains

The list covers every questionnaire in your account, not just the surveys you are running today. Besides the questions of your active surveys it includes:

questions from archived surveys
deleted questions, marked with is_deleted: true
questions from questionnaires that no survey uses any more
questions from 360° feedback questionnaires, whose surveys /v1/surveys does not return

If you want to rebuild the structure of one particular survey, expect /v1/questions to return more than that survey asks.

Question IDs and surveys

Why the same text appears under several IDs

Every question ID belongs to exactly one questionnaire. How a survey gets its questionnaire decides whether it shares IDs with other surveys:

A survey created from a template (for example the Pulse Survey) or from scratch gets its own new questionnaire. All of its questions receive new IDs, even when their text is identical to a question in another survey.
A survey created with Reuse existing shares the questionnaire of the survey it was based on, and therefore uses the same question IDs.

Both cases usually occur in the same account. An account that created 30 surveys from the same template therefore returns each template question 30 times, each time with a different id. This is expected, not duplicated data.

Question IDs are not stable across surveys. Do not treat an id as the key for “the same question” over time or across surveys. To group questions that ask the same thing, match on the question text in name, or on dimension once it is available.

Mapping a question to its survey

The Export API currently has no field that links a question to a survey: the question object carries no survey reference, and /v1/surveys does not list a survey’s questions. You cannot tell from these two endpoints which survey a question ID belongs to.

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Response Fields

​What the list contains

​Question IDs and surveys

​Why the same text appears under several IDs

​Mapping a question to its survey

Endpoint

Query Parameters

Example Request

Example Response

Response Fields

What the list contains

Question IDs and surveys

Why the same text appears under several IDs

Mapping a question to its survey