# Surveys ## List surveys `client.surveys.list(SurveyListParamsparams?, RequestOptionsoptions?): CursorPage` **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 ### Parameters - `params: SurveyListParams` - `cursor?: string` Query param: An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page. - `isActive?: boolean | null` Query param: Filter by active status - `limit?: number` Query param: A limit on the number of objects to be returned, between 1 and 100. - `type?: "text" | "link" | "rating" | "multiple-choice"` Query param: Filter by survey page type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Survey` - `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` Survey pages - `id: string` Page ID - `title: string` Page title - `type: "text" | "link" | "rating" | "multiple-choice"` Page type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `allowSelectMultiple?: boolean` Allow multiple selections - `choices?: Array` Available choices - `id: string` Choice ID - `choice?: string` Choice text - `defaultAction?: SurveyNextAction` Action to take if condition matches - `type: "page" | "end" | "next"` Type of next action - `"page"` - `"end"` - `"next"` - `pageId?: string` Page ID to navigate to - `description?: string` Page description - `highLabel?: string` Label for high rating - `linkButtonText?: string` Button text for link - `linkRedirectUrl?: string` URL to redirect to - `linkTarget?: "_blank" | "_self" | "_parent" | "_top"` Link target - `"_blank"` - `"_self"` - `"_parent"` - `"_top"` - `logic?: Array` Conditional logic rules - `comparator: string` Comparison operator - `next: SurveyNextAction` Action to take if condition matches - `value: string | number | Array` Value to compare against - `string` - `number` - `Array` - `id?: string` Logic rule ID - `lowLabel?: string` Label for low rating - `placeholder?: string` Placeholder for text input - `scale?: number` Rating scale - `subType?: "number" | "emoji" | "generic" | 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?: string` Survey description - `targeting?: Targeting` Targeting configuration - `css?: Array` CSS selector targeting rules - `value: string` CSS selector - `loginRequired?: boolean` Whether login is required - `segmentIds?: Array` Segment IDs to target - `url?: Array` URL targeting rules - `matchType: "exact" | "contains" | "regex"` Type of URL matching - `"exact"` - `"contains"` - `"regex"` - `value: string` URL pattern to match - `id?: string` Rule ID ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const survey of client.surveys.list()) { console.log(survey.id); } ``` #### 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 `client.surveys.retrieve(stringid, SurveyRetrieveParamsparams?, RequestOptionsoptions?): Survey` **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 ### Parameters - `id: string` Survey unique identifier - `params: SurveyRetrieveParams` - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Survey` - `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` Survey pages - `id: string` Page ID - `title: string` Page title - `type: "text" | "link" | "rating" | "multiple-choice"` Page type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `allowSelectMultiple?: boolean` Allow multiple selections - `choices?: Array` Available choices - `id: string` Choice ID - `choice?: string` Choice text - `defaultAction?: SurveyNextAction` Action to take if condition matches - `type: "page" | "end" | "next"` Type of next action - `"page"` - `"end"` - `"next"` - `pageId?: string` Page ID to navigate to - `description?: string` Page description - `highLabel?: string` Label for high rating - `linkButtonText?: string` Button text for link - `linkRedirectUrl?: string` URL to redirect to - `linkTarget?: "_blank" | "_self" | "_parent" | "_top"` Link target - `"_blank"` - `"_self"` - `"_parent"` - `"_top"` - `logic?: Array` Conditional logic rules - `comparator: string` Comparison operator - `next: SurveyNextAction` Action to take if condition matches - `value: string | number | Array` Value to compare against - `string` - `number` - `Array` - `id?: string` Logic rule ID - `lowLabel?: string` Label for low rating - `placeholder?: string` Placeholder for text input - `scale?: number` Rating scale - `subType?: "number" | "emoji" | "generic" | 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?: string` Survey description - `targeting?: Targeting` Targeting configuration - `css?: Array` CSS selector targeting rules - `value: string` CSS selector - `loginRequired?: boolean` Whether login is required - `segmentIds?: Array` Segment IDs to target - `url?: Array` URL targeting rules - `matchType: "exact" | "contains" | "regex"` Type of URL matching - `"exact"` - `"contains"` - `"regex"` - `value: string` URL pattern to match - `id?: string` Rule ID ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); const survey = await client.surveys.retrieve('6743752ca81ae59d25cf834b'); console.log(survey.id); ``` #### 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 `client.surveys.listResponses(stringid, SurveyListResponsesParamsparams?, RequestOptionsoptions?): CursorPage` **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 ### Parameters - `id: string` Survey unique identifier - `params: SurveyListResponsesParams` - `cursor?: string` Query param: An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page. - `limit?: number` Query param: A limit on the number of objects to be returned, between 1 and 100. - `pageId?: string` Query param: Filter by survey page ID - `featurebaseVersion?: "2026-01-01.nova" | "2025-12-12.clover"` Header param: API version for this request. Defaults to your organization's configured API version if not specified. - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `SurveyListResponsesResponse` - `id: string` Unique identifier - `createdAt: string` ISO 8601 timestamp when created - `object: "survey_response"` Object type identifier - `"survey_response"` - `responses: Array` Individual responses to questions - `pageId: string` Page ID this response is for - `type: "text" | "link" | "rating" | "multiple-choice"` Response type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `value: string | number | boolean | Array` Response value - `string` - `number` - `boolean` - `Array` - `id?: string` Response ID - `createdAt?: string` ISO 8601 timestamp when created - `updatedAt?: string` ISO 8601 timestamp when updated - `user: Contact | null` User who submitted the response - `id: string` Unique identifier - `name: string` Contact display name - `object: "contact"` Object type identifier - `"contact"` - `type: "customer" | "lead"` Type of contact - `"customer"` - `"lead"` - `commentsCreated?: number` Number of comments created - `companies?: Array` Companies the contact belongs to - `id: string` Featurebase internal ID - `companyId: string` External company ID from your system - `companySize: number | null` Company employee headcount - `createdAt: string | null` ISO date when company was created - `industry: string | null` Industry - `lastActivity: string | null` ISO date of last activity - `linkedUsers: number | null` Number of users linked to this company - `monthlySpend: number | null` Monthly spend - `name: string` Company name - `object: "company"` Object type identifier - `"company"` - `plan: string | null` Plan or tier name - `updatedAt: string | null` ISO date when company was last updated - `website: string | null` Company website URL - `customFields?: Record` Custom field values - `customFields?: Record` Custom field values on the contact - `description?: string` Contact description/bio - `email?: string | null` Contact email - `lastActivity?: string` Last activity ISO timestamp - `locale?: string` Contact locale - `manuallyOptedOutFromChangelog?: boolean` Whether manually opted out from changelog - `organizationId?: string` Organization ID the contact belongs to - `postsCreated?: number` Number of posts created - `profilePicture?: string | null` Profile picture URL - `roles?: Array` Contact roles - `subscribedToChangelog?: boolean` Whether subscribed to changelog - `userId?: string` External user ID from SSO - `verified?: boolean` Whether email is verified ### Example ```typescript import Featurebase from 'featurebase-node'; const client = new Featurebase({ apiKey: process.env['FEATUREBASE_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const surveyListResponsesResponse of client.surveys.listResponses( '6743752ca81ae59d25cf834b', )) { console.log(surveyListResponsesResponse.id); } ``` #### 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` - `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` Survey pages - `id: string` Page ID - `title: string` Page title - `type: "text" | "link" | "rating" | "multiple-choice"` Page type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `allowSelectMultiple?: boolean` Allow multiple selections - `choices?: Array` Available choices - `id: string` Choice ID - `choice?: string` Choice text - `defaultAction?: SurveyNextAction` Action to take if condition matches - `type: "page" | "end" | "next"` Type of next action - `"page"` - `"end"` - `"next"` - `pageId?: string` Page ID to navigate to - `description?: string` Page description - `highLabel?: string` Label for high rating - `linkButtonText?: string` Button text for link - `linkRedirectUrl?: string` URL to redirect to - `linkTarget?: "_blank" | "_self" | "_parent" | "_top"` Link target - `"_blank"` - `"_self"` - `"_parent"` - `"_top"` - `logic?: Array` Conditional logic rules - `comparator: string` Comparison operator - `next: SurveyNextAction` Action to take if condition matches - `value: string | number | Array` Value to compare against - `string` - `number` - `Array` - `id?: string` Logic rule ID - `lowLabel?: string` Label for low rating - `placeholder?: string` Placeholder for text input - `scale?: number` Rating scale - `subType?: "number" | "emoji" | "generic" | 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?: string` Survey description - `targeting?: Targeting` Targeting configuration - `css?: Array` CSS selector targeting rules - `value: string` CSS selector - `loginRequired?: boolean` Whether login is required - `segmentIds?: Array` Segment IDs to target - `url?: Array` URL targeting rules - `matchType: "exact" | "contains" | "regex"` Type of URL matching - `"exact"` - `"contains"` - `"regex"` - `value: string` URL pattern to match - `id?: string` Rule ID ### Survey Next Action - `SurveyNextAction` Action to take if condition matches - `type: "page" | "end" | "next"` Type of next action - `"page"` - `"end"` - `"next"` - `pageId?: string` Page ID to navigate to ### Survey List Responses Response - `SurveyListResponsesResponse` - `id: string` Unique identifier - `createdAt: string` ISO 8601 timestamp when created - `object: "survey_response"` Object type identifier - `"survey_response"` - `responses: Array` Individual responses to questions - `pageId: string` Page ID this response is for - `type: "text" | "link" | "rating" | "multiple-choice"` Response type - `"text"` - `"link"` - `"rating"` - `"multiple-choice"` - `value: string | number | boolean | Array` Response value - `string` - `number` - `boolean` - `Array` - `id?: string` Response ID - `createdAt?: string` ISO 8601 timestamp when created - `updatedAt?: string` ISO 8601 timestamp when updated - `user: Contact | null` User who submitted the response - `id: string` Unique identifier - `name: string` Contact display name - `object: "contact"` Object type identifier - `"contact"` - `type: "customer" | "lead"` Type of contact - `"customer"` - `"lead"` - `commentsCreated?: number` Number of comments created - `companies?: Array` Companies the contact belongs to - `id: string` Featurebase internal ID - `companyId: string` External company ID from your system - `companySize: number | null` Company employee headcount - `createdAt: string | null` ISO date when company was created - `industry: string | null` Industry - `lastActivity: string | null` ISO date of last activity - `linkedUsers: number | null` Number of users linked to this company - `monthlySpend: number | null` Monthly spend - `name: string` Company name - `object: "company"` Object type identifier - `"company"` - `plan: string | null` Plan or tier name - `updatedAt: string | null` ISO date when company was last updated - `website: string | null` Company website URL - `customFields?: Record` Custom field values - `customFields?: Record` Custom field values on the contact - `description?: string` Contact description/bio - `email?: string | null` Contact email - `lastActivity?: string` Last activity ISO timestamp - `locale?: string` Contact locale - `manuallyOptedOutFromChangelog?: boolean` Whether manually opted out from changelog - `organizationId?: string` Organization ID the contact belongs to - `postsCreated?: number` Number of posts created - `profilePicture?: string | null` Profile picture URL - `roles?: Array` Contact roles - `subscribedToChangelog?: boolean` Whether subscribed to changelog - `userId?: string` External user ID from SSO - `verified?: boolean` Whether email is verified