# Surveys ## List surveys **get** `/v2/surveys` Returns all surveys configured in your Featurebase organization. ### Query Parameters - `limit` - Number of items to return (1-100, default 10) - `cursor` - Cursor for pagination - `type` - Filter by survey page type (text, link, rating, multiple-choice) - `isActive` - Filter by active status ### Response Format Returns a list object with: - `object` - Always "list" - `data` - Array of survey objects - `nextCursor` - Cursor for next page (null if no more results) ### Survey Object Each survey includes: - `id` - Unique identifier - `title` - Survey title - `description` - Survey description - `isActive` - Whether the survey is active - `responseCount` - Number of responses received - `targeting` - Targeting configuration (segments, URLs, CSS selectors) - `pages` - Array of survey pages/questions - `createdAt` - ISO 8601 timestamp when created - `updatedAt` - ISO 8601 timestamp when last updated ### Query Parameters - `cursor: optional string` An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page. - `isActive: optional boolean` Filter by active status - `limit: optional number` A limit on the number of objects to be returned, between 1 and 100. - `type: optional "text" or "link" or "rating" or "multiple-choice"` Filter by survey page type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `data: array of Survey` Array of surveys - `id: string` Unique identifier - `createdAt: string` ISO 8601 timestamp when created - `isActive: boolean` Whether the survey is active - `object: "survey"` Object type identifier - `"survey"` - `organization: string` Organization ID - `pages: array of object { id, title, type, 13 more }` Survey pages - `id: string` Page ID - `title: string` Page title - `type: "text" or "link" or "rating" or "multiple-choice"` Page type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `allowSelectMultiple: optional boolean` Allow multiple selections - `choices: optional array of object { id, choice }` Available choices - `id: string` Choice ID - `choice: optional string` Choice text - `defaultAction: optional SurveyNextAction` Action to take if condition matches - `type: "page" or "end" or "next"` Type of next action - `"page"` - `"end"` - `"next"` - `pageId: optional string` Page ID to navigate to - `description: optional string` Page description - `highLabel: optional string` Label for high rating - `linkButtonText: optional string` Button text for link - `linkRedirectUrl: optional string` URL to redirect to - `linkTarget: optional "_blank" or "_self" or "_parent" or "_top"` Link target - `"_blank"` - `"_self"` - `"_parent"` - `"_top"` - `logic: optional array of object { comparator, next, value, id }` Conditional logic rules - `comparator: string` Comparison operator - `next: SurveyNextAction` Action to take if condition matches - `value: string or number or array of string` Value to compare against - `string` - `number` - `array of string` - `id: optional string` Logic rule ID - `lowLabel: optional string` Label for low rating - `placeholder: optional string` Placeholder for text input - `scale: optional number` Rating scale - `subType: optional "number" or "emoji" or "generic" or 2 more` Sub-type for rating/multiple-choice - `"number"` - `"emoji"` - `"generic"` - `"featurebase-posts"` - `"nps"` - `responseCount: number` Number of responses - `title: string` Survey title - `updatedAt: string` ISO 8601 timestamp when last updated - `description: optional string` Survey description - `targeting: optional object { css, loginRequired, segmentIds, url }` Targeting configuration - `css: optional array of object { value }` CSS selector targeting rules - `value: string` CSS selector - `loginRequired: optional boolean` Whether login is required - `segmentIds: optional array of string` Segment IDs to target - `url: optional array of object { matchType, value, id }` URL targeting rules - `matchType: "exact" or "contains" or "regex"` Type of URL matching - `"exact"` - `"contains"` - `"regex"` - `value: string` URL pattern to match - `id: optional string` Rule ID - `nextCursor: string` Cursor for fetching the next page (cursor-based pagination) - `object: "list"` Object type identifier - `"list"` ### Example ```http curl https://do.featurebase.app/v2/surveys \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "data": [ { "id": "6743752ca81ae59d25cf834b", "createdAt": "2024-11-24T18:49:16.755Z", "isActive": true, "object": "survey", "organization": "5febde12dc56d60012d47db6", "pages": [ { "id": "6743752ca81ae59d25cf834c", "title": "How happy are you with our product?", "type": "rating", "allowSelectMultiple": false, "choices": [ { "id": "66dc54128b989696d050008b", "choice": "Very satisfied" } ], "defaultAction": { "type": "page", "pageId": "6743754dd8bf964ec2562cda" }, "description": "We really want to hear from you.", "highLabel": "It's awesome!", "linkButtonText": "Visit our website", "linkRedirectUrl": "https://example.com", "linkTarget": "_blank", "logic": [ { "comparator": "less than", "next": { "type": "page", "pageId": "6743754dd8bf964ec2562cda" }, "value": 4, "id": "6743755fd8bf964ec2562cdb" } ], "lowLabel": "Could be improved", "placeholder": "Type your answer here", "scale": 5, "subType": "emoji" } ], "responseCount": 85, "title": "Get feedback for Feedback module", "updatedAt": "2025-04-10T08:58:51.148Z", "description": "Measure what we can improve", "targeting": { "css": [ { "value": ".feedback-button" } ], "loginRequired": false, "segmentIds": [ "6636438b7fcdc515999042eb" ], "url": [ { "matchType": "contains", "value": "/dashboard/posts", "id": "674375cfd8bf964ec2562cdc" } ] } } ], "nextCursor": null, "object": "list" } ``` ## Get a survey by ID **get** `/v2/surveys/{id}` Retrieves a single survey by its unique identifier. Returns the survey object if found in your organization. ### Response Returns a survey object with: - `id` - Unique identifier - `title` - Survey title - `description` - Survey description - `isActive` - Whether the survey is active - `responseCount` - Number of responses received - `targeting` - Targeting configuration - `pages` - Array of survey pages/questions - `createdAt` - ISO 8601 timestamp when created - `updatedAt` - ISO 8601 timestamp when last updated ### Survey Pages Each page represents a question or screen in the survey: - `type` - Page type (text, link, rating, multiple-choice) - `title` - Question title - `description` - Optional description - `logic` - Conditional logic rules - `defaultAction` - Default action when no logic matches ### Errors - `404` - Survey not found in your organization ### Path Parameters - `id: string` Survey unique identifier ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Survey object { id, createdAt, isActive, 8 more }` - `id: string` Unique identifier - `createdAt: string` ISO 8601 timestamp when created - `isActive: boolean` Whether the survey is active - `object: "survey"` Object type identifier - `"survey"` - `organization: string` Organization ID - `pages: array of object { id, title, type, 13 more }` Survey pages - `id: string` Page ID - `title: string` Page title - `type: "text" or "link" or "rating" or "multiple-choice"` Page type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `allowSelectMultiple: optional boolean` Allow multiple selections - `choices: optional array of object { id, choice }` Available choices - `id: string` Choice ID - `choice: optional string` Choice text - `defaultAction: optional SurveyNextAction` Action to take if condition matches - `type: "page" or "end" or "next"` Type of next action - `"page"` - `"end"` - `"next"` - `pageId: optional string` Page ID to navigate to - `description: optional string` Page description - `highLabel: optional string` Label for high rating - `linkButtonText: optional string` Button text for link - `linkRedirectUrl: optional string` URL to redirect to - `linkTarget: optional "_blank" or "_self" or "_parent" or "_top"` Link target - `"_blank"` - `"_self"` - `"_parent"` - `"_top"` - `logic: optional array of object { comparator, next, value, id }` Conditional logic rules - `comparator: string` Comparison operator - `next: SurveyNextAction` Action to take if condition matches - `value: string or number or array of string` Value to compare against - `string` - `number` - `array of string` - `id: optional string` Logic rule ID - `lowLabel: optional string` Label for low rating - `placeholder: optional string` Placeholder for text input - `scale: optional number` Rating scale - `subType: optional "number" or "emoji" or "generic" or 2 more` Sub-type for rating/multiple-choice - `"number"` - `"emoji"` - `"generic"` - `"featurebase-posts"` - `"nps"` - `responseCount: number` Number of responses - `title: string` Survey title - `updatedAt: string` ISO 8601 timestamp when last updated - `description: optional string` Survey description - `targeting: optional object { css, loginRequired, segmentIds, url }` Targeting configuration - `css: optional array of object { value }` CSS selector targeting rules - `value: string` CSS selector - `loginRequired: optional boolean` Whether login is required - `segmentIds: optional array of string` Segment IDs to target - `url: optional array of object { matchType, value, id }` URL targeting rules - `matchType: "exact" or "contains" or "regex"` Type of URL matching - `"exact"` - `"contains"` - `"regex"` - `value: string` URL pattern to match - `id: optional string` Rule ID ### Example ```http curl https://do.featurebase.app/v2/surveys/$ID \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "6743752ca81ae59d25cf834b", "createdAt": "2024-11-24T18:49:16.755Z", "isActive": true, "object": "survey", "organization": "5febde12dc56d60012d47db6", "pages": [ { "id": "6743752ca81ae59d25cf834c", "title": "How happy are you with our product?", "type": "rating", "allowSelectMultiple": false, "choices": [ { "id": "66dc54128b989696d050008b", "choice": "Very satisfied" } ], "defaultAction": { "type": "page", "pageId": "6743754dd8bf964ec2562cda" }, "description": "We really want to hear from you.", "highLabel": "It's awesome!", "linkButtonText": "Visit our website", "linkRedirectUrl": "https://example.com", "linkTarget": "_blank", "logic": [ { "comparator": "less than", "next": { "type": "page", "pageId": "6743754dd8bf964ec2562cda" }, "value": 4, "id": "6743755fd8bf964ec2562cdb" } ], "lowLabel": "Could be improved", "placeholder": "Type your answer here", "scale": 5, "subType": "emoji" } ], "responseCount": 85, "title": "Get feedback for Feedback module", "updatedAt": "2025-04-10T08:58:51.148Z", "description": "Measure what we can improve", "targeting": { "css": [ { "value": ".feedback-button" } ], "loginRequired": false, "segmentIds": [ "6636438b7fcdc515999042eb" ], "url": [ { "matchType": "contains", "value": "/dashboard/posts", "id": "674375cfd8bf964ec2562cdc" } ] } } ``` ## Get survey responses **get** `/v2/surveys/{id}/responses` Retrieves all user responses for a specific survey. ### Query Parameters - `pageId` - Filter responses to a specific survey page - `limit` - Number of items to return (1-100, default 10) - `cursor` - Cursor for pagination ### Response Format Returns a list object with: - `object` - Always "list" - `data` - Array of survey response objects - `nextCursor` - Cursor for next page (null if no more results) ### Survey Response Object Each response includes: - `id` - Unique response identifier - `user` - User who submitted the response (may be null for anonymous) - `responses` - Array of individual answers - `createdAt` - ISO 8601 timestamp when submitted ### Individual Response Each item in the responses array: - `pageId` - The survey page this response is for - `type` - Response type (text, rating, multiple-choice) - `value` - The response value ### Errors - `404` - Survey not found in your organization ### Path Parameters - `id: string` Survey unique identifier ### Query Parameters - `cursor: optional string` An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page. - `limit: optional number` A limit on the number of objects to be returned, between 1 and 100. - `pageId: optional string` Filter by survey page ID ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `data: array of object { id, createdAt, object, 2 more }` Array of survey responses - `id: string` Unique identifier - `createdAt: string` ISO 8601 timestamp when created - `object: "survey_response"` Object type identifier - `"survey_response"` - `responses: array of object { pageId, type, value, 3 more }` Individual responses to questions - `pageId: string` Page ID this response is for - `type: "text" or "link" or "rating" or "multiple-choice"` Response type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `value: string or number or boolean or array of string` Response value - `string` - `number` - `boolean` - `array of string` - `id: optional string` Response ID - `createdAt: optional string` ISO 8601 timestamp when created - `updatedAt: optional string` ISO 8601 timestamp when updated - `user: Contact` User who submitted the response - `id: string` Unique identifier - `name: string` Contact display name - `object: "contact"` Object type identifier - `"contact"` - `type: "customer" or "lead"` Type of contact - `"customer"` - `"lead"` - `commentsCreated: optional number` Number of comments created - `companies: optional array of Company` Companies the contact belongs to - `id: string` Featurebase internal ID - `companyId: string` External company ID from your system - `companySize: number` Company employee headcount - `createdAt: string` ISO date when company was created - `industry: string` Industry - `lastActivity: string` ISO date of last activity - `linkedUsers: number` Number of users linked to this company - `monthlySpend: number` Monthly spend - `name: string` Company name - `object: "company"` Object type identifier - `"company"` - `plan: string` Plan or tier name - `updatedAt: string` ISO date when company was last updated - `website: string` Company website URL - `customFields: optional map[unknown]` Custom field values - `customFields: optional map[unknown]` Custom field values on the contact - `description: optional string` Contact description/bio - `email: optional string` Contact email - `lastActivity: optional string` Last activity ISO timestamp - `locale: optional string` Contact locale - `manuallyOptedOutFromChangelog: optional boolean` Whether manually opted out from changelog - `organizationId: optional string` Organization ID the contact belongs to - `postsCreated: optional number` Number of posts created - `profilePicture: optional string` Profile picture URL - `roles: optional array of string` Contact roles - `subscribedToChangelog: optional boolean` Whether subscribed to changelog - `userId: optional string` External user ID from SSO - `verified: optional boolean` Whether email is verified - `nextCursor: string` Cursor for fetching the next page (cursor-based pagination) - `object: "list"` Object type identifier - `"list"` ### Example ```http curl https://do.featurebase.app/v2/surveys/$ID/responses \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "data": [ { "id": "6712e2d175904ce24b2f9637", "createdAt": "2024-10-18T22:36:01.269Z", "object": "survey_response", "responses": [ { "pageId": "66dc53c5a64824f0e84a4c1e", "type": "multiple-choice", "value": [ "66dc54128b989696d050008b" ], "id": "6712e2d175904ce24b2f9638", "createdAt": "2024-10-18T22:36:01.270Z", "updatedAt": "2024-10-18T22:36:01.270Z" } ], "user": { "id": "676f0f6765bdaa7d7d760f88", "name": "John Steezy", "object": "contact", "type": "customer", "commentsCreated": 0, "companies": [ { "id": "507f1f77bcf86cd799439011", "companyId": "comp_12345", "companySize": 250, "createdAt": "2025-01-01T12:00:00.000Z", "industry": "Technology", "lastActivity": "2025-01-15T00:00:00.000Z", "linkedUsers": 15, "monthlySpend": 5000, "name": "Acme Inc", "object": "company", "plan": "enterprise", "updatedAt": "2025-01-10T15:30:00.000Z", "website": "https://acme.com", "customFields": { "location": "bar", "priority": "bar" } } ], "customFields": { "foo": "bar" }, "description": "", "email": "john@example.com", "lastActivity": "2025-01-03T21:42:30.181Z", "locale": "en", "manuallyOptedOutFromChangelog": false, "organizationId": "5febde12dc56d60012d47db6", "postsCreated": 0, "profilePicture": "https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png", "roles": [ "string" ], "subscribedToChangelog": true, "userId": "676f0f673dbb299c8a4f3057", "verified": true } } ], "nextCursor": null, "object": "list" } ``` ## Domain Types ### Survey - `Survey object { id, createdAt, isActive, 8 more }` - `id: string` Unique identifier - `createdAt: string` ISO 8601 timestamp when created - `isActive: boolean` Whether the survey is active - `object: "survey"` Object type identifier - `"survey"` - `organization: string` Organization ID - `pages: array of object { id, title, type, 13 more }` Survey pages - `id: string` Page ID - `title: string` Page title - `type: "text" or "link" or "rating" or "multiple-choice"` Page type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `allowSelectMultiple: optional boolean` Allow multiple selections - `choices: optional array of object { id, choice }` Available choices - `id: string` Choice ID - `choice: optional string` Choice text - `defaultAction: optional SurveyNextAction` Action to take if condition matches - `type: "page" or "end" or "next"` Type of next action - `"page"` - `"end"` - `"next"` - `pageId: optional string` Page ID to navigate to - `description: optional string` Page description - `highLabel: optional string` Label for high rating - `linkButtonText: optional string` Button text for link - `linkRedirectUrl: optional string` URL to redirect to - `linkTarget: optional "_blank" or "_self" or "_parent" or "_top"` Link target - `"_blank"` - `"_self"` - `"_parent"` - `"_top"` - `logic: optional array of object { comparator, next, value, id }` Conditional logic rules - `comparator: string` Comparison operator - `next: SurveyNextAction` Action to take if condition matches - `value: string or number or array of string` Value to compare against - `string` - `number` - `array of string` - `id: optional string` Logic rule ID - `lowLabel: optional string` Label for low rating - `placeholder: optional string` Placeholder for text input - `scale: optional number` Rating scale - `subType: optional "number" or "emoji" or "generic" or 2 more` Sub-type for rating/multiple-choice - `"number"` - `"emoji"` - `"generic"` - `"featurebase-posts"` - `"nps"` - `responseCount: number` Number of responses - `title: string` Survey title - `updatedAt: string` ISO 8601 timestamp when last updated - `description: optional string` Survey description - `targeting: optional object { css, loginRequired, segmentIds, url }` Targeting configuration - `css: optional array of object { value }` CSS selector targeting rules - `value: string` CSS selector - `loginRequired: optional boolean` Whether login is required - `segmentIds: optional array of string` Segment IDs to target - `url: optional array of object { matchType, value, id }` URL targeting rules - `matchType: "exact" or "contains" or "regex"` Type of URL matching - `"exact"` - `"contains"` - `"regex"` - `value: string` URL pattern to match - `id: optional string` Rule ID ### Survey Next Action - `SurveyNextAction object { type, pageId }` Action to take if condition matches - `type: "page" or "end" or "next"` Type of next action - `"page"` - `"end"` - `"next"` - `pageId: optional string` Page ID to navigate to ### Survey List Responses Response - `SurveyListResponsesResponse object { id, createdAt, object, 2 more }` - `id: string` Unique identifier - `createdAt: string` ISO 8601 timestamp when created - `object: "survey_response"` Object type identifier - `"survey_response"` - `responses: array of object { pageId, type, value, 3 more }` Individual responses to questions - `pageId: string` Page ID this response is for - `type: "text" or "link" or "rating" or "multiple-choice"` Response type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `value: string or number or boolean or array of string` Response value - `string` - `number` - `boolean` - `array of string` - `id: optional string` Response ID - `createdAt: optional string` ISO 8601 timestamp when created - `updatedAt: optional string` ISO 8601 timestamp when updated - `user: Contact` User who submitted the response - `id: string` Unique identifier - `name: string` Contact display name - `object: "contact"` Object type identifier - `"contact"` - `type: "customer" or "lead"` Type of contact - `"customer"` - `"lead"` - `commentsCreated: optional number` Number of comments created - `companies: optional array of Company` Companies the contact belongs to - `id: string` Featurebase internal ID - `companyId: string` External company ID from your system - `companySize: number` Company employee headcount - `createdAt: string` ISO date when company was created - `industry: string` Industry - `lastActivity: string` ISO date of last activity - `linkedUsers: number` Number of users linked to this company - `monthlySpend: number` Monthly spend - `name: string` Company name - `object: "company"` Object type identifier - `"company"` - `plan: string` Plan or tier name - `updatedAt: string` ISO date when company was last updated - `website: string` Company website URL - `customFields: optional map[unknown]` Custom field values - `customFields: optional map[unknown]` Custom field values on the contact - `description: optional string` Contact description/bio - `email: optional string` Contact email - `lastActivity: optional string` Last activity ISO timestamp - `locale: optional string` Contact locale - `manuallyOptedOutFromChangelog: optional boolean` Whether manually opted out from changelog - `organizationId: optional string` Organization ID the contact belongs to - `postsCreated: optional number` Number of posts created - `profilePicture: optional string` Profile picture URL - `roles: optional array of string` Contact roles - `subscribedToChangelog: optional boolean` Whether subscribed to changelog - `userId: optional string` External user ID from SSO - `verified: optional boolean` Whether email is verified