Survey Results

API documentation

Programmatically generate survey links and read back responses and statuses from external systems such as Salesforce, background jobs, or custom integrations.

Authentication & Key Hygiene

Every request must include an API key as a Bearer token in the Authorization header. Generate and manage keys from Account → API keys.

Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx

Key Hygiene and Security Notice

API keys grant full access to your account data, including participant names, emails, and survey responses. Keep keys secure:

  • Create dedicated API keys per integration.
  • Never commit keys to source control or expose them in client-side / browser code.
  • Revoke and re-issue keys immediately if compromised.
  • Monitor the Last used timestamp in Account settings to verify expected activity.

Rate limits

API requests are capped at 120 requests per minute per API key. Every API response includes standard rate limit headers:

FieldTypeRequiredNotes
X-RateLimit-LimitintegerNoMaximum allowed requests in the current 60-second window (120).
X-RateLimit-RemainingintegerNoRemaining requests permitted in the active window.
X-RateLimit-ResetintegerNoUnix epoch timestamp (seconds) when the current rate limit window resets.
Retry-AfterintegerNoReturned on 429 responses: seconds to wait before retrying.

Note on window boundary bursts: A request burst spanning a 60-second fixed-window boundary can briefly reach up to twice the rate limit.

Pagination

List and lookup endpoints use keyset cursor pagination. Callers provide an optional limit (1 to 500, default 500) and pass the opaque nextCursor as cursor to fetch the next page.

Every paginated response always includes the exact totalRecords count, a hasNext flag, and a ready-to-call nextPageUrl (the same request URL with cursor swapped in), so you can fetch the next page without reconstructing query parameters. There is no opt-in flag for any of this, it is always present.

A cursor remembers the sort order it was issued under. Reusing a cursor with a different order value than the request that produced it returns invalid_cursor rather than silently wrong results.

Pagination block shape

{
  "pagination": {
    "limit": 500,
    "hasNext": true,
    "totalRecords": 842,
    "nextCursor": "eyJ0IjoiMjAyNi0wOC0xNFQwOToxNTowMC4wMDBaIiwiaWQiOiJhMWIyYzNkNCIsIm8iOiJkZXNjIn0",
    "nextPageUrl": "https://www.surveyresults.online/api/v1/responses?surveyId=R8fULqa1&limit=500&cursor=eyJ0IjoiMjAyNi0wOC0xNFQwOToxNTowMC4wMDBaIiwiaWQiOiJhMWIyYzNkNCIsIm8iOiJkZXNjIn0"
  }
}

List Survey

GET/api/v1/surveys

List all surveys in your account with embedded response counts and completion rates.

Query Parameters

FieldTypeRequiredNotes
statusstringNoFilter by status: draft, published, archived.
qstringNoCase-insensitive title search.
limitintegerNoPage size (1 to 500, default 500).
cursorstringNoOpaque pagination cursor from nextCursor.
orderstringNoSort direction: asc or desc (default desc).

Request

curl -G "https://www.surveyresults.online/api/v1/surveys" \
  -H "Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "status=published" \
  --data-urlencode "limit=500"

Response Example

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "surveyId": "R8fULqa1",
      "title": "Customer Satisfaction Survey",
      "description": "Quarterly CSAT survey",
      "status": "published",
      "publishedVersionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "expiresAt": null,
      "createdAt": "2026-08-01T10:00:00.000Z",
      "updatedAt": "2026-08-10T14:30:00.000Z",
      "counts": {
        "links": 240,
        "responses": 173
      },
      "completionRate": 0.72
    }
  ],
  "pagination": {
    "limit": 500,
    "hasNext": false,
    "totalRecords": 1,
    "nextCursor": null,
    "nextPageUrl": null
  }
}

Survey Details

GET/api/v1/surveys/:surveyId

Retrieve survey metadata and its version history. This endpoint does not include field (question) definitions. To map answer keys to labels, use the fields array returned alongside a survey's responses (see List Responses), or request format=labeled there directly.

Request

curl "https://www.surveyresults.online/api/v1/surveys/R8fULqa1" \
  -H "Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response Example

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "surveyId": "R8fULqa1",
    "title": "Customer Satisfaction Survey",
    "description": "Quarterly feedback",
    "status": "published",
    "expiresAt": null,
    "publishedVersion": {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "versionNumber": 1,
      "publishedAt": "2026-08-01T10:00:00.000Z"
    },
    "versions": [
      {
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "versionNumber": 1,
        "status": "published",
        "publishedAt": "2026-08-01T10:00:00.000Z"
      }
    ]
  }
}

List Responses

GET/api/v1/responses

Query submitted responses across surveys or filter by survey, participant email, or date range.

Query Parameters

FieldTypeRequiredNotes
surveyIdstringNoFilter responses to one survey (short code or UUID).
emailstringNoFilter by participant email (case-insensitive exact match).
tokenstringNoFilter by survey link token.
fromstringNoEarliest submitted_at ISO timestamp.
tostringNoLatest submitted_at ISO timestamp.
formatstringNoraw (default), labeled, or both. Requires surveyId.
meta.<key>stringNoFilter by one metadata key on the response's own survey link, e.g. meta.plan=Pro.
limitintegerNoPage size (1 to 500, default 500).
cursorstringNoPagination cursor from nextCursor.
orderstringNoasc or desc (default desc).

Request

curl -G "https://www.surveyresults.online/api/v1/responses" \
  -H "Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "surveyId=R8fULqa1" \
  --data-urlencode "format=both"

Response Example (format=both)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "surveyId": "R8fULqa1",
      "submittedAt": "2026-08-14T09:15:00.000Z",
      "timeToCompleteSeconds": 95,
      "participant": {
        "name": "Jane Doe",
        "email": "jane@example.com",
        "token": "aB3dE9fH2kL7mN1p"
      },
      "metadata": {
        "city": "Mumbai",
        "plan": "Pro"
      },
      "answers": {
        "fld_nps123": 10,
        "fld_fb456": "Great service!"
      },
      "answersByLabel": {
        "How likely are you to recommend us?": "10",
        "What can we improve?": "Great service!"
      }
    }
  ],
  "fields": [
    {
      "id": "fld_nps123",
      "label": "How likely are you to recommend us?",
      "type": "nps"
    },
    {
      "id": "fld_fb456",
      "label": "What can we improve?",
      "type": "long_text"
    }
  ],
  "pagination": {
    "limit": 500,
    "hasNext": false,
    "totalRecords": 1,
    "nextCursor": null,
    "nextPageUrl": null
  }
}

Response Details

Get response by id

GET/api/v1/responses/:id

Retrieve full details for a single response. Field definitions and answer values are resolved through the exact survey version pinned to the participant's link. Fields conditionally hidden during completion report visible: false.

Request

curl "https://www.surveyresults.online/api/v1/responses/a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d" \
  -H "Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response Example

{
  "data": {
    "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "surveyId": "R8fULqa1",
    "submittedAt": "2026-08-14T09:15:00.000Z",
    "timeToCompleteSeconds": 95,
    "participant": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "token": "aB3dE9fH2kL7mN1p"
    },
    "metadata": {
      "city": "Mumbai",
      "plan": "Pro"
    },
    "surveyVersion": {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "versionNumber": 1
    },
    "fields": [
      {
        "id": "fld_nps123",
        "label": "How likely are you to recommend us?",
        "type": "nps",
        "value": 10,
        "displayValue": "10",
        "visible": true
      },
      {
        "id": "fld_followup",
        "label": "Why did you choose that score?",
        "type": "long_text",
        "value": null,
        "displayValue": "-",
        "visible": false
      }
    ]
  }
}

Look up responses by email

GET/api/v1/responses/lookup

For integrations that know a participant's email rather than our internal response id. email is required; when name is also supplied, both must match the same participant (exact, case-insensitive). If a participant has more than one matching response, this is not treated as an error, every match is returned, newest first, in the same rich per-field detail shape as /api/v1/responses/:id above, using the same pagination as the list endpoint.

Query Parameters

FieldTypeRequiredNotes
emailstringYesParticipant email (case-insensitive exact match).
namestringNoParticipant name. When set, matched together with email.
surveyIdstringNoRestrict the search to one survey. Omit to search the whole account.
limitintegerNoPage size (1 to 500, default 500).
cursorstringNoPagination cursor from nextCursor.
orderstringNoasc or desc (default desc).

Request

curl -G "https://www.surveyresults.online/api/v1/responses/lookup" \
  -H "Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "email=jane@example.com" \
  --data-urlencode "surveyId=R8fULqa1"

Response Example

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "surveyId": "R8fULqa1",
      "submittedAt": "2026-08-14T09:15:00.000Z",
      "timeToCompleteSeconds": 95,
      "participant": {
        "name": "Jane Doe",
        "email": "jane@example.com",
        "token": "aB3dE9fH2kL7mN1p"
      },
      "metadata": {
        "city": "Mumbai",
        "plan": "Pro"
      },
      "surveyVersion": {
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "versionNumber": 1
      },
      "fields": [
        {
          "id": "fld_nps123",
          "label": "How likely are you to recommend us?",
          "type": "nps",
          "value": 10,
          "displayValue": "10",
          "visible": true
        }
      ]
    }
  ],
  "pagination": {
    "limit": 500,
    "hasNext": false,
    "totalRecords": 1,
    "nextCursor": null,
    "nextPageUrl": null
  }
}

Error codes

All error responses follow the standard format:

{
  "error": "Survey not found",
  "code": "survey_not_found"
}

Standard Error Codes

CodeStatusDescription
unauthorized401Missing, invalid, or revoked Bearer API key.
forbidden403Legacy response code returned only by POST /api/v1/survey/create-links when a survey exists but belongs to another account.
survey_not_found404Survey ID does not exist or belongs to another account (read endpoints return 404 to prevent resource existence leaks).
response_not_found404Response does not exist or belongs to another account.
link_not_found404Survey link token does not exist or belongs to another account.
invalid_cursor422Cursor is malformed or sort order direction (asc/desc) does not match the cursor.
invalid_limit422Limit is not an integer between 1 and 500.
invalid_query422Malformed query parameter, such as requesting format=labeled without providing surveyId, or a lookup call missing the required email parameter.
rate_limited429Rate limit of 120 requests/minute exceeded. Check Retry-After header.
server_error500Internal server error occurred while processing the request.