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_xxxxxxxxxxxxxxxxxxxxxxxxKey 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:
| Field | Type | Required | Notes |
|---|---|---|---|
| X-RateLimit-Limit | integer | No | Maximum allowed requests in the current 60-second window (120). |
| X-RateLimit-Remaining | integer | No | Remaining requests permitted in the active window. |
| X-RateLimit-Reset | integer | No | Unix epoch timestamp (seconds) when the current rate limit window resets. |
| Retry-After | integer | No | Returned 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
/api/v1/surveysList all surveys in your account with embedded response counts and completion rates.
Query Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
| status | string | No | Filter by status: draft, published, archived. |
| q | string | No | Case-insensitive title search. |
| limit | integer | No | Page size (1 to 500, default 500). |
| cursor | string | No | Opaque pagination cursor from nextCursor. |
| order | string | No | Sort 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
/api/v1/surveys/:surveyIdRetrieve 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"
}
]
}
}Create Survey Links
/api/v1/survey/create-linksGenerates unique, individual survey links for a list of participants. No email is sent by the platform; your system delivers the generated links to respondents.
Within a single batch request, duplicates with identical name and email (case-insensitive) are skipped so only one link is created.
Request Body
| Field | Type | Required | Notes |
|---|---|---|---|
| surveyId | string | Yes | Survey short code or UUID. Must be published. |
| participants | array | Yes | 1 to 1000 participant objects. |
| participants[].name | string | Yes | Participant full name (max 200 chars). |
| participants[].email | string | Yes | Valid email address. |
| participants[].metadata | object | No | Your own context for this participant (city, plan, record id). Stored as sent and returned by the read endpoints below. |
| expiresAt | string | No | Optional ISO timestamp for link expiry. Must be in the future. |
Metadata
Send anything your system knows about the participant. Nested objects are flattened with dots, so {"address": {"city": "Mumbai"}} is stored as address.city. Arrays of simple values are kept as they are. Values must be text, numbers, booleans or null.
Limits, applied after flattening:
| Field | Type | Required | Notes |
|---|---|---|---|
| keys | 50 max | No | Counted after nested objects are flattened. |
| key length | 128 chars | No | The full dotted path. |
| value length | 500 chars | No | Text values. Longer values are rejected, not truncated. |
| nesting | 5 dots max | No | So address.city is fine, and a deeper path is rejected. |
| total size | 8 KB | No | Per participant. |
Metadata is validated per participant, so one bad object fails only that entry and the rest of the batch still gets links. The reason appears in errors[] and names the key at fault.
Values are stored exactly as you send them and are readable by any API key on your account, so treat them the way you treat the rest of your participant data.
Request
curl -X POST "https://www.surveyresults.online/api/v1/survey/create-links" \
-H "Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"surveyId": "R8fULqa1",
"participants": [
{
"name": "Jane Doe",
"email": "jane@example.com",
"metadata": { "city": "Mumbai", "plan": "Pro", "crmId": "003XX000004TmiQ" }
}
],
"expiresAt": "2026-09-30T23:59:59Z"
}'Response
{
"success": true,
"surveyId": "R8fULqa1",
"sent": 1,
"failed": 0,
"invitations": [
{
"name": "Jane Doe",
"email": "jane@example.com",
"surveyUrl": "https://www.surveyresults.online/s/aB3dE9fH2kL7mN1p",
"token": "aB3dE9fH2kL7mN1p",
"expiresAt": "2026-09-30T23:59:59.000Z"
}
],
"errors": []
}Survey Links
Inspect the status of generated survey links across participants. Status values (pending, opened, completed, expired) are evaluated in real time against link expiration.
List survey links
/api/v1/survey-linksQuery Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
| surveyId | string | No | Filter by survey short code or UUID. |
| string | No | Filter by participant email (case-insensitive exact match). | |
| status | string | No | pending, opened, completed, expired. |
| from | string | No | Earliest link creation ISO timestamp. |
| to | string | No | Latest link creation ISO timestamp. |
| meta.<key> | string | No | Filter by one metadata key, e.g. meta.city=Mumbai. Matched as text, so a number or boolean value still matches its string form. |
| limit | integer | No | Page size (1 to 500, default 500). |
| cursor | string | No | Pagination cursor from nextCursor. |
| order | string | No | asc or desc (default desc). |
Request
curl -G "https://www.surveyresults.online/api/v1/survey-links" \
-H "Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
--data-urlencode "surveyId=R8fULqa1" \
--data-urlencode "status=completed"Response Example
{
"data": [
{
"id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"token": "aB3dE9fH2kL7mN1p",
"surveyUrl": "https://www.surveyresults.online/s/aB3dE9fH2kL7mN1p",
"surveyId": "R8fULqa1",
"status": "completed",
"participant": {
"name": "Jane Doe",
"email": "jane@example.com"
},
"metadata": {
"city": "Mumbai",
"plan": "Pro"
},
"createdAt": "2026-08-14T08:00:00.000Z",
"openedAt": "2026-08-14T09:12:00.000Z",
"completedAt": "2026-08-14T09:15:00.000Z",
"expiresAt": "2026-08-31T23:59:59.000Z",
"responseId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
}
],
"pagination": {
"limit": 500,
"hasNext": false,
"totalRecords": 1,
"nextCursor": null,
"nextPageUrl": null
}
}Get survey link by token
/api/v1/survey-links/:tokenCheck the status of an individual survey link by its token. If completed, the embedded response record and answers are included directly.
Request
curl "https://www.surveyresults.online/api/v1/survey-links/aB3dE9fH2kL7mN1p" \
-H "Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx"Response Example
{
"data": {
"token": "aB3dE9fH2kL7mN1p",
"surveyUrl": "https://www.surveyresults.online/s/aB3dE9fH2kL7mN1p",
"surveyId": "R8fULqa1",
"status": "completed",
"participant": {
"name": "Jane Doe",
"email": "jane@example.com"
},
"metadata": {
"city": "Mumbai",
"plan": "Pro"
},
"createdAt": "2026-08-14T08:00:00.000Z",
"openedAt": "2026-08-14T09:12:00.000Z",
"completedAt": "2026-08-14T09:15:00.000Z",
"expiresAt": "2026-08-31T23:59:59.000Z",
"responseId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"response": {
"id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"submittedAt": "2026-08-14T09:15:00.000Z",
"answers": {
"fld_nps123": 10,
"fld_fb456": "Great service!"
}
}
}
}Look up survey links by email
/api/v1/survey-links/lookupFor integrations that know a participant's email rather than a link token. 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 link, this is not treated as an error, every match is returned, newest first, using the same pagination as the list endpoint above.
Query Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
| string | Yes | Participant email (case-insensitive exact match). | |
| name | string | No | Participant name. When set, matched together with email. |
| surveyId | string | No | Restrict the search to one survey. Omit to search the whole account. |
| limit | integer | No | Page size (1 to 500, default 500). |
| cursor | string | No | Pagination cursor from nextCursor. |
| order | string | No | asc or desc (default desc). |
Request
curl -G "https://www.surveyresults.online/api/v1/survey-links/lookup" \
-H "Authorization: Bearer svy_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
--data-urlencode "email=jane@example.com" \
--data-urlencode "surveyId=R8fULqa1"Response Example
{
"data": [
{
"id": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"token": "aB3dE9fH2kL7mN1p",
"surveyUrl": "https://www.surveyresults.online/s/aB3dE9fH2kL7mN1p",
"surveyId": "R8fULqa1",
"status": "completed",
"participant": {
"name": "Jane Doe",
"email": "jane@example.com"
},
"metadata": {
"city": "Mumbai",
"plan": "Pro"
},
"createdAt": "2026-08-14T08:00:00.000Z",
"openedAt": "2026-08-14T09:12:00.000Z",
"completedAt": "2026-08-14T09:15:00.000Z",
"expiresAt": "2026-08-31T23:59:59.000Z",
"responseId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"response": {
"id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"submittedAt": "2026-08-14T09:15:00.000Z",
"answers": {
"fld_nps123": 10,
"fld_fb456": "Great service!"
}
}
}
],
"pagination": {
"limit": 500,
"hasNext": false,
"totalRecords": 1,
"nextCursor": null,
"nextPageUrl": null
}
}List Responses
/api/v1/responsesQuery submitted responses across surveys or filter by survey, participant email, or date range.
Query Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
| surveyId | string | No | Filter responses to one survey (short code or UUID). |
| string | No | Filter by participant email (case-insensitive exact match). | |
| token | string | No | Filter by survey link token. |
| from | string | No | Earliest submitted_at ISO timestamp. |
| to | string | No | Latest submitted_at ISO timestamp. |
| format | string | No | raw (default), labeled, or both. Requires surveyId. |
| meta.<key> | string | No | Filter by one metadata key on the response's own survey link, e.g. meta.plan=Pro. |
| limit | integer | No | Page size (1 to 500, default 500). |
| cursor | string | No | Pagination cursor from nextCursor. |
| order | string | No | asc 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
/api/v1/responses/:idRetrieve 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
/api/v1/responses/lookupFor 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
| Field | Type | Required | Notes |
|---|---|---|---|
| string | Yes | Participant email (case-insensitive exact match). | |
| name | string | No | Participant name. When set, matched together with email. |
| surveyId | string | No | Restrict the search to one survey. Omit to search the whole account. |
| limit | integer | No | Page size (1 to 500, default 500). |
| cursor | string | No | Pagination cursor from nextCursor. |
| order | string | No | asc 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
| Code | Status | Description |
|---|---|---|
| unauthorized | 401 | Missing, invalid, or revoked Bearer API key. |
| forbidden | 403 | Legacy response code returned only by POST /api/v1/survey/create-links when a survey exists but belongs to another account. |
| survey_not_found | 404 | Survey ID does not exist or belongs to another account (read endpoints return 404 to prevent resource existence leaks). |
| response_not_found | 404 | Response does not exist or belongs to another account. |
| link_not_found | 404 | Survey link token does not exist or belongs to another account. |
| invalid_cursor | 422 | Cursor is malformed or sort order direction (asc/desc) does not match the cursor. |
| invalid_limit | 422 | Limit is not an integer between 1 and 500. |
| invalid_query | 422 | Malformed query parameter, such as requesting format=labeled without providing surveyId, or a lookup call missing the required email parameter. |
| rate_limited | 429 | Rate limit of 120 requests/minute exceeded. Check Retry-After header. |
| server_error | 500 | Internal server error occurred while processing the request. |