Quickstart

This guide takes you from an API key to the answers your respondents gave, in six calls. You will check your key, find a survey, get the link respondents open, and read the responses and statistics. Every step is a plain curl command you can paste into a terminal.

Before you start

• Your organization's plan includes API access. If it doesn't, every call answers 403 API_ACCESS_NOT_IN_TIER.
• You are an owner or admin of the organization. Only they can create API keys.
• A survey to read. This guide only reads, so if you have none yet, create one in the dashboard or through the API as Building a survey shows.

Create an API key

In the dashboard, open Settings → API keys and create a key with the scopes surveys:read and responses:read. That is everything this guide needs.

A token starts with sfk_live_ and the key's 12-character public prefix. The prefix is safe to log and shows up in the dashboard's key list; the rest of the token is the secret.

Set up your shell

Put the API address and your token into two environment variables, so the commands below work as written:

export SF_API="https://simplefeedback.de/api"
export SF_KEY="sfk_live_..."

Every request sends the token as a bearer token: Authorization: Bearer $SF_KEY.

Check the key

GET /v1/me needs no scope. It is the quickest way to tell a wrong token from a missing scope.

curl "$SF_API/v1/me" -H "Authorization: Bearer $SF_KEY"

{
  "organizationId": "934c6a69-ed8e-4110-ba37-644a84047341",
  "tier": "BUSINESS",
  "scopes": ["surveys:read", "responses:read"],
  "venueId": null,
  "prefix": "V1StGXR8Z5jd"
}

A 401 means the token is wrong, revoked or expired. A 403 means the token is fine but the plan or the scopes are not.

Find your survey

List your surveys, newest first:

curl "$SF_API/v1/surveys?limit=5" -H "Authorization: Bearer $SF_KEY"

{
  "data": [
    {
      "id": "a1b2c3d4-0001-4001-8001-000000000001",
      "name": "Customer satisfaction",
      "venueId": "35ce5fe3-69c6-4daf-a2b2-eb64e8840d43",
      "active": true,
      "responseCount": 34,
      "createdAt": "2026-10-07T20:01:05.870Z",
      "updatedAt": "2026-10-07T20:01:05.870Z"
    }
  ],
  "pagination": { "total": 1, "limit": 5, "offset": 0 }
}

Copy the id of the survey you want and keep it in a variable:

export SURVEY_ID="a1b2c3d4-0001-4001-8001-000000000001"

The list only carries summaries. GET /v1/surveys/$SURVEY_ID returns the whole survey, including its questions.

Get the link respondents open

curl "$SF_API/v1/surveys/$SURVEY_ID/qr" -H "Authorization: Bearer $SF_KEY"

{
  "publicUrl": "https://simplefeedback.de/p/a1b2c3d4-0001-4001-8001-000000000001",
  "qrDataUrl": "data:image/png;base64,iVBORw0KGgo..."
}

publicUrl is the page a respondent opens. qrDataUrl is a 512 px PNG of a QR code for that link.

Nothing is created by this call: the link and the image are the same every time. Responses that come in through them are saved like any other, but opening the link is not counted as a scan. For printed codes that count their scans, see Distributing a survey.

Read the responses

curl "$SF_API/v1/surveys/$SURVEY_ID/responses?limit=25" -H "Authorization: Bearer $SF_KEY"

{
  "data": [
    {
      "id": "cmuyjadna0002tl7dp2red0lc",
      "submittedAt": "2026-10-07T17:22:41.873Z",
      "answers": [
        { "questionId": "q_5d9e5ad2", "rating": 4 },
        { "questionId": "q_d39b94f8", "score": 9 },
        { "questionId": "q_2e8d9bb9", "text": "Lovely terrace, a bit slow at lunch." }
      ],
      "metadata": { "elapsedMs": 48210 }
    }
  ],
  "pagination": { "total": 34, "limit": 25, "offset": 0 }
}

Each answer names the question it belongs to by questionId. The question texts are in the survey itself, under modules[].questions[] in GET /v1/surveys/$SURVEY_ID.

Responses come newest first, 25 per page by default and at most 100. Page through older ones with offset:

curl "$SF_API/v1/surveys/$SURVEY_ID/responses?limit=100&offset=100" -H "Authorization: Bearer $SF_KEY"

To keep a copy of every response in your own system, follow Syncing results.

Get the numbers

If you want results rather than single answers, the statistics endpoint does the counting for you:

curl "$SF_API/v1/surveys/$SURVEY_ID/statistics" -H "Authorization: Bearer $SF_KEY"

{
  "pollId": "a1b2c3d4-0001-4001-8001-000000000001",
  "totalResponses": 34,
  "analyzedResponses": 34,
  "truncated": false,
  "questionStats": [
    {
      "questionId": "q_5d9e5ad2",
      "questionText": "How satisfied were you with your visit?",
      "questionType": "rating",
      "totalAnswered": 34,
      "distribution": { "1": 1, "2": 0, "3": 7, "4": 16, "5": 10 },
      "percentages": { "1": 2.9, "2": 0, "3": 20.6, "4": 47.1, "5": 29.4 },
      "average": 4,
      "median": 4
    }
  ]
}

Unlike a response, every entry here already carries its questionText.

Next steps

• Every route, request body and response shape is in the API reference.
• Code generators can read the raw OpenAPI document.
• Each key is limited to 60 requests per minute and route. Every response tells you where you stand in the X-RateLimit-Remaining and X-RateLimit-Reset headers.
• Before an integration runs unattended, read Running an integration in production.