Honestly Export API: Make Your First API Call

This quickstart walks you through making your first successful API call to Honestly’s Export API — from obtaining your API key to pulling a live list of your surveys. By the end, you will have a working request you can adapt for employees, questions, scores, initiatives, and more.

Get your API key

If you have the Admin role, you can create your own API key inside Honestly. In your account settings, open API keys, choose Create API key, and give the key a descriptive name. The key value is shown only once, right after you create it — copy it immediately and store it somewhere safe, because you will not be able to view it again later.

The API keys page requires the API Access (Business Intelligence) add-on. If your account does not have it, the menu item does not appear at all — in that case, email service@honestly.com to have access enabled.

Store the key as an environment variable rather than pasting it directly into your scripts:

export HONESTLY_API_KEY="YOUR_SECRET_API_KEY"

You can then reference $HONESTLY_API_KEY in all subsequent requests, keeping the key out of your source code and version history.

Make your first request

With your key in hand, call the surveys endpoint to retrieve the list of surveys in your account:

curl -X GET "https://api.honestly.com/v1/surveys" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"

A successful response will look similar to this:

{
  "total_count": 3,
  "surveys": [
    {
      "id": 101,
      "name": { "en": "Q2 2025 Employee Engagement Survey", "de": "Mitarbeiterbefragung Q2 2025" },
      "is_deactivated": false,
      "is_archived": false,
      "next_survey_starts_at": "2025-07-01T09:00:00Z",
      "current_survey_ends_at": "2025-06-30T23:59:59Z"
    },
    {
      "id": 102,
      "name": { "en": "Onboarding Experience — June 2025", "de": "Onboarding-Erlebnis — Juni 2025" },
      "is_deactivated": false,
      "is_archived": false,
      "next_survey_starts_at": null,
      "current_survey_ends_at": "2025-06-15T23:59:59Z"
    },
    {
      "id": 103,
      "name": { "en": "Manager Effectiveness Pulse", "de": "Puls zur Führungskräfte-Effektivität" },
      "is_deactivated": true,
      "is_archived": true,
      "next_survey_starts_at": null,
      "current_survey_ends_at": null
    }
  ]
}

The total_count field tells you the total number of surveys in your account, regardless of how many were returned in this page.

Paginate through results

All list endpoints use offset-based pagination controlled by two query parameters:

limit — the maximum number of records to return per page (e.g. 100)
offset — the number of records to skip before returning results (e.g. 100 to start at the second page)

To fetch the second page of surveys with a page size of 100:

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

To determine when you have reached the last page, compare the current offset plus the number of records returned in the response against the total_count value. When offset + count >= total_count, you have retrieved all available records.

Export employees and responses

The same request pattern — authenticate with X-Api-Key, paginate with limit and offset — works across all Export API resources:

Endpoint	Description
`GET /v1/employees`	Retrieve employee records and roles
`GET /v1/questions`	Access questions across all surveys
`GET /v1/survey_assignments`	See which employees are assigned to which surveys
`GET /v1/scores`	Pull aggregated, anonymity-protected engagement scores
`GET /v1/initiatives`	List initiatives (action items) derived from survey results

Refer to the API Reference section for full parameter details, filtering options, and response schemas for each endpoint.

Use the total_count field in every list response to calculate how many pages to fetch. See Pagination for a complete guide.