> ## Documentation Index
> Fetch the complete documentation index at: https://help.honestly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Honestly Export API: Make Your First API Call

> Learn how to authenticate and make your first call to the Honestly Export API in under 5 minutes. Export surveys, employees, and scores.

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.

<Steps>
  <Step title="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](mailto: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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Make your first request">
    With your key in hand, call the surveys endpoint to retrieve the list of surveys in your account:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  Use the `total_count` field in every list response to calculate how many pages to fetch. See [Pagination](/developers/concepts/pagination) for a complete guide.
</Tip>