GET /v1/surveys — List and Filter Surveys by Status

The /v1/surveys endpoint returns a paginated list of all surveys in your Honestly account, including their schedule, status, permissions, and custom properties.

Endpoint

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

Query Parameters

integer

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

integer

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

string

RFC 3339 datetime. Return only surveys created at or after this date. URL-encode the value when passing it as a query parameter.

boolean

Filter surveys by archived status. Set to true to return only archived surveys, or false to return only non-archived surveys. Omit this parameter to return all surveys regardless of archived status.

Example Request

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

Example Response

{
  "total_count": 2,
  "surveys": [
    {
      "id": 23,
      "import_id": null,
      "name": {
        "en": "Q4 Employee Engagement",
        "de": "Q4 Mitarbeiterbefragung"
      },
      "frequency": "monthly",
      "created_at": "2024-01-01T09:00:00Z",
      "start_at": "2024-01-01T09:00:00Z",
      "end_at": null,
      "archived_at": null,
      "current_survey_ends_at": "2024-01-22T23:59:59Z",
      "next_survey_starts_at": "2024-01-15T09:00:00Z",
      "is_archived": false,
      "is_deactivated": false,
      "permissions": {
        "employees_with_access_to_results": [1, 12, 33]
      },
      "survey_properties": [
        {
          "id": 5,
          "name": "Type",
          "survey_property_options": [
            { "id": 9, "name": "Pulse surveys" }
          ]
        }
      ]
    },
    {
      "id": 24,
      "import_id": "x23344b",
      "name": {
        "en": "Onboarding Pulse",
        "de": "Onboarding Puls"
      },
      "frequency": "once",
      "created_at": "2023-09-10T08:00:00Z",
      "start_at": "2023-09-11T08:00:00Z",
      "end_at": "2023-10-11T08:00:00Z",
      "archived_at": "2023-11-01T08:00:00Z",
      "current_survey_ends_at": null,
      "next_survey_starts_at": null,
      "is_archived": true,
      "is_deactivated": false,
      "permissions": {
        "employees_with_access_to_results": []
      },
      "survey_properties": []
    }
  ]
}

Response Fields

integer

Total number of surveys matching the query. Use this value to calculate how many pages to fetch when paginating.

array

List of survey objects.

Show survey object fields

integer

Unique identifier for the survey.

string | null

The identifier assigned when the survey was created through the Honestly Import API. null when the survey was created in the web application.

object

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

string

How often an employee can participate in this survey. One of weekly, biweekly, monthly, or once.

string

RFC 3339 datetime the survey was created.

string | null

RFC 3339 datetime of the survey start. null when the survey started on its created_at date.

string | null

RFC 3339 datetime of the survey end. null when no end date is defined.

string | null

RFC 3339 datetime the survey was archived. null when the survey was never archived.

string | null

RFC 3339 datetime when the current survey participation period ends. null if the survey is closed or the current period is not yet open.

string | null

RFC 3339 datetime when the survey opens next. null if the survey is closed.

boolean

Whether the survey has been archived.

boolean

Whether the survey has been deactivated. Deactivated surveys are no longer sent to employees.

object

Access control for the survey results.

Show permissions fields

array of integers

The employee IDs that have access to this survey’s results.

array

Customer-defined properties used to segment surveys.

Show survey property fields

integer

Unique identifier for the property.

string

The property name.

array

The available options for this property, each with an id (integer) and name (string).

The frequency field uses an extensible enum — new values may be added as Honestly introduces new functionality. Make sure your code handles unknown values gracefully.

Use total_count to calculate how many pages to fetch. See Pagination for a complete walkthrough.

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Response Fields

Endpoint

Query Parameters

Example Request

Example Response

Response Fields