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

API keys are issued by your dedicated Honestly Customer Success manager. If you don’t have one yet, email service@honestly.com to request access.Once you receive your key, store it 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.