Implementing custom surveys

Last updated:

|Edit this page

Note: This is not required for popover surveys.

If you're using PostHog's survey API to create a custom survey UI, there are 2 steps to integrating with PostHog:

Step 1: Fetch active surveys

To fetch the surveys currently enabled for a user, call posthog.getActiveMatchingSurveys(callback, forceReload).

Alternatively, if you wish to do survey targeting yourself, you can call posthog.getSurveys(callback, forceReload) to return a list of all surveys from PostHog.

Surveys are cached by default in the posthog-js library, so you can pass true to forceReload to force a new surveys api call from PostHog.

Both methods return a callback with an array of surveys:

// Example surveys response:
"id": "your_survey_id",
"name": "Your survey name",
"description": "Metadata describing your survey",
"type": "api", // can be either "api" or "popover"
"linked_flag_key": null, //Linked feature flag key, if any.
"targeting_flag_key": "your_survey_targeting_flag_key",
"questions": [
"type": "single_choice",
"choices": [
"question": "Are you enjoying PostHog?"
"conditions": null,
"start_date": "2023-09-19T13:10:49.505000Z",
"end_date": null

Thus you can use show your user a survey using code like this:

posthog.getActiveMatchingSurveys((surveys) => {
// Make sure you filter for surveys that are of type `"api"`.
// This prevents accidentally showing popover surveys to your users.
const filteredSurveys = surveys.filter(survey => survey.type === 'api'));
if (filteredSurveys.length > 0) {
// show the survey using your custom UI

Important: posthog.getActiveMatchingSurveys() will always return an active survey if the user meets the targeting conditions, even if they have already seen, dismissed or responded to the survey.

Note: If you're using a URL or selector targeting options, you'll need to poll posthog.getActiveMatchingSurveys() to get the most updated results.

Step 2: Capture survey events

To show survey results in PostHog, you need to capture user interactions with your surveys using the following 3 events:

// 1. When a user is shown a survey
posthog.capture("survey shown", {
$survey_id: {} // required
// 2. When a user has dismissed a survey
posthog.capture("survey dismissed", {
$survey_id: {} // required
// 3. When a user has responded to a survey
posthog.capture("survey sent", {
$survey_id: {} // required
$survey_response: {survey_response} // required. `{survey_response}` must be a text or number value (depending on your question type).
// For multiple choice select surveys, `{survey_response}` must be an array of values with the selected choices.
// e.g., $survey_response: ["response_1", 8, "response_2"]

Multiple question surveys

If you have a survey with multiple questions, you can capture the responses to each question using the following syntax:

posthog.capture("survey sent", {
$survey_id: {} // required
$survey_response: {survey_response}
$survey_response_1: {survey_response_1}
$survey_response_2: {survey_response_2}

If you want to make the most of PostHog's automatic survey analysis and results visualizations page, you'll need to capture survey responses in the above formats.


Was this page useful?

Next article

Viewing survey results

Survey results can be viewed in two places: On the survey page, in the "Results" tab. By creating your own insights . 1. On the survey page You can view your results by selecting your survey from the surveys tab . You'll see data on: How many users have seen the survey. How many users have dismissed the survey. Responses. Depending your question type , you may also see charts with your responses. 2. Creating your own insights To create insights from survey results, navigate to the insights…

Read next article