As established in the Core API overview, surveys are one of the four essential pillars of the Goodays environment. While the Core API provides the endpoints necessary to consult and list your survey resources, this section explores the internal logic and data formats that power them.

A Goodays survey is a dynamic tool designed to capture the nuances of the end customer experience. It can range from a single satisfaction question to a complex, multi-path journey using "Mother-Daughter" conditional logic. Understanding these structures is critical for several key technical workflows:

Interpreting Data: Correcty parsing the JSON results returned by the Response API.
Pushing participations: Formatting the answers array correctly when using the Collect API to import external data.
Data Analysis: Understanding how specific question types (like NPS or Stars) contribute to the calculated values in the Metrics API.

The following guide details every question type available in Goodays and how their data is structured in both the survey definition and the end customer's participation.

Survey Question Types & Structures

Goodays surveys are highly customizable and support a wide variety of question formats—ranging from simple text inputs to complex, conditional logic (mother-daughter questions).

When querying the Response API understanding the type of question and its configuration in the options object is crucial for properly parsing the participation data.

Core Question Object Structure

Before diving into specific types, it's important to understand the basic structure of a question in the Goodays Survey API. Each question object contains standard metadata:

{
    "id": "nlxDYWQJ8M",
    "position": 1,
    "title": "How would you rate your overall experience at Jurassic Park?",
    "enabled": true,
    "type": "stars",
    "enabled_at": "2026-03-11T17:09:21.776819+01:00",
    "disabled_at": null,
    "options": {},
    "sub_questions": []
}

type: Defines the format of the question (e.g., stars, text, nps).
options: A configuration object containing type-specific parameters (e.g., alert limit, skippable flags).
sub_questions: An array containing conditional "daughter" questions that are triggered based on the end customer's answer.

Supported Question Types

Here is a detailed breakdown of all available question type values, including how they are configured in the survey definition and how the end customer's answer is formatted in the Response API payload.

1. Stars Rating (`stars`)

Used for standard 1-to-5 star rating scales.

Configuration: The options object can include an alert_limit (e.g., 2).
Answer format: The value is an Integer representing the number of stars selected.

Answer example:

{
    "value": 2,
    "question": {
        "id": "nlxDYWQJ8M",
        "title": "How would you rate your overall experience at Jurassic Park?",
        "type": "stars"
    }
}

2. Customer Satisfaction (`csat`)

A metric used to measure end customer satisfaction, often represented visually as a scale (e.g., 1 to 5).

Configuration: The options object can include an alert_limit (e.g., 2).
Answer format: The value is an Integer.

Answer example:

{
    "value": 2,
    "question": {
        "id": "yLdLYQpm4j",
        "title": "How satisfied were you with the organization and flow of your visit to Jurassic Park?",
        "type": "csat"
    }
}

3. Net Promoter Score (`nps`)

Used to measure end customer loyalty. It asks how likely the end customer is to recommend the business on a scale of 0 to 10.

Configuration: The options object can include an alert_limit (e.g., 2).
Answer format: The value is an Integer (0-10).

Answer example:

{
    "value": 4,
    "question": {
        "id": "Q54E5XpK4y",
        "title": "How likely are you to recommend Jurassic Park to a friend or family member?",
        "type": "nps"
    }
}

4. Open-ended Text (`text`)

A free-form text input field for end customers to leave a verbatim.

Configuration: Typically uses an empty options object (unless configured as skippable).
Answer format: The value is a String.

Answer example:

{
    "value": "More raptor !",
    "question": {
        "id": "Zmxo3QWqxj",
        "title": "What could we improve to make your next visit to Jurassic Park even better?",
        "type": "text"
    }
}

5. Single Choice (`choices`)

A list of options where the end customer can only select one answer.

Configuration: The options object contains an array of choices (Strings).
Answer format: The value is a String exactly matching the chosen option.

Survey Configuration Example:

"options": {
    "choices": [
        "The T-Rex encounter",
        "The raptor zone",
        "The dinosaur safari tour"
    ]
}

Answer example:

{
    "value": "The raptor zone",
    "question": {
        "id": "k6xmwOvKdj",
        "title": "What was the highlight of your visit to Jurassic Park?",
        "type": "choices"
    }
}

6. Multiple Choice (`multiple_answers`)

A list of options where the end customer can select one or more answers.

Configuration: The options object contains an array of available choices.
Answer format: The value is an Array of Strings, containing all selected options.

Survey Configuration Example:

"options": {
    "choices": [
        "Waiting time was too long",
        "The park was difficult to navigate",
        "Staff assistance was not sufficient"
    ]
}

Answer example:

{
    "value": [
        "Some attractions were unavailable",
        "Staff assistance was not sufficient"
    ],
    "question": {
        "id": "pe8NzlDM8j",
        "title": "What was the main issue during your visit?",
        "type": "multiple_answers"
    }
}

7. Emoji Sentiment (`emoji`)

A visual scale using emojis instead of numbers to capture sentiment.

Configuration: The options object contains an array of labels corresponding to the emojis.
Answer format: The value is a String matching the label of the selected emoji.

Survey Configuration Example:

"options": {
    "labels": [
        "Not impressed at all",
        "Slightly impressed",
        "Quite impressed",
        "Very impressed"
    ]
}

Answer example:

{
    "value": "Very impressed",
    "question": {
        "id": "bJdY1E6OdR",
        "title": "How did you feel when you saw the dinosaurs for the first time?",
        "type": "emoji"
    }
}

8. Boolean Yes/No (`yesno`)

A simple binary choice.

Configuration: Usually empty options.
Answer format: The value is a String representing the end customer's localized choice (e.g., "Oui", "Non", "Yes", "No").
Pushing a participation: When you send answers through the Collect API (POST /responses/collect) or the legacy retrieval (POST /responses), the value must be an Integer: 1 for yes, 0 for no. Any other value returns a validation error.

Answer example:

{
    "value": "Non",
    "question": {
        "id": "ELxjqVoV4K",
        "title": "Did you feel safe during your visit to Jurassic Park?",
        "type": "yesno"
    }
}

9. Customer Effort Score (`ces`)

Used to measure the effort perceived by the end customer during a key interaction. The end customer says whether they agree with a statement (the question title), on a scale from 1 (Strongly disagree) to 7 (Strongly agree). A high score means a low effort.

Unlike nps and csat, a survey can contain several ces questions (for example one per step of a journey).

Configuration: The options object can include an alert_limit (e.g., 3).
Answer format: The value is an Integer (1-7).

Answer example:

{
    "value": 6,
    "question": {
        "id": "Q54E5XpK4y",
        "title": "It was easy to book my tickets for Jurassic Park.",
        "type": "ces"
    }
}

See CES - Customer Effort Score to retrieve the calculated CES with the Metrics API.

Advanced Behaviors

Conditional Logic (Mother-Daughter Questions)

Goodays supports nested conditional questions. In the survey structure, a "Mother" question will contain a sub_questions array. Each "Daughter" question inside this array includes a triggers array.

The daughter question is only displayed to the end customer if their answer to the mother question matches one of the values in the triggers array.

Example Logic:
If an end customer gives a low CSAT score (1 or 2), we want to ask what went wrong. If they give a high score (4 or 5), we want to ask what worked best.

{
    "id": "yLdLYQpm4j",
    "title": "How satisfied were you with the organization and flow of your visit?",
    "type": "csat",
    "sub_questions": [
        {
            "id": "pe8NzlDM8j",
            "triggers": [1, 2],
            "title": "What was the main issue during your visit?",
            "type": "multiple_answers"
        },
        {
            "id": "158yQm678w",
            "triggers": [4, 5],
            "title": "What worked best during your visit?",
            "type": "multiple_answers"
        }
    ]
}

Note: In the Response API payload, if a daughter question is triggered and answered, it will appear in the flat answers array alongside the mother question.

Skippable Questions

Any question type can be configured as optional. This is defined in the options object of the question by adding a boolean flag and an optional custom label.

"options": {
    "skippable_label": "Skip this question",
    "skippable": true
}

If an end customer skips a question, it will simply not appear in the answers array of their participation.

Handling Alerts (`alert_triggered`)

Score-based questions (specifically Stars Rating (stars), Customer Satisfaction (csat), Net Promoter Score (nps) and Customer Effort Score (ces)) can be configured with an alert_limit in their options object.

If an end customer submits a score that is equal to or lower than this limit, it triggers a dissatisfaction alert.

In the Response API payload, this is represented by the alert_triggered boolean located at the root of the participation object (not inside the individual answer).

Example of a participation triggering an alert:
Here, the end customer gave a CSAT score of 2, which hit the alert limit threshold.

{
    "id": "6xmpPLON4j",
    "created_date": "2026-03-12T10:59:52.108239+01:00",
    "answers": [
        {
            "value": 2,
            "question": {
                "id": "yLdLYQpm4j",
                "title": "How satisfied were you with the organization and flow of your visit to Jurassic Park?",
                "type": "csat"
            }
        }
    ],
    "state": "open",
    "alert_triggered": true
}

Appendix: Complete JSON Examples

For reference, here are complete JSON payloads illustrating a full survey structure configuration and the corresponding Response API output.

1. Complete Survey Structure Example

This JSON represents a full survey configuration, including various question types and mother-daughter logic.

{
    "id": "yLdLGNm8j1",
    "slug": "jp_post_visit",
    "label": "Jurassic Park - Post Visit",
    "enabled": true,
    "questions": [
        {
            "id": "nlxDYWQJ8M",
            "position": 1,
            "title": "How would you rate your overall experience at Jurassic Park?",
            "enabled": true,
            "type": "stars",
            "enabled_at": "2026-03-11T17:09:21.776819+01:00",
            "disabled_at": null,
            "options": {},
            "sub_questions": [
                {
                    "id": "Qe4Z1qMndp",
                    "triggers": [4, 5],
                    "title": "What made your experience memorable?",
                    "enabled": true,
                    "type": "multiple_answers",
                    "enabled_at": "2026-03-11T17:09:21.782354+01:00",
                    "disabled_at": null,
                    "options": {
                        "choices": [
                            "The realism of the dinosaurs",
                            "The excitement of the visit",
                            "The immersive environment",
                            "The quality of the attractions"
                        ]
                    }
                }
            ]
        },
        {
            "id": "yLdLYQpm4j",
            "position": 2,
            "title": "How satisfied were you with the organization and flow of your visit to Jurassic Park?",
            "enabled": true,
            "type": "csat",
            "enabled_at": "2026-03-11T17:09:21.785423+01:00",
            "disabled_at": null,
            "options": {},
            "sub_questions": [
                {
                    "id": "pe8NzlDM8j",
                    "triggers": [1, 2],
                    "title": "What was the main issue during your visit?",
                    "enabled": true,
                    "type": "multiple_answers",
                    "enabled_at": "2026-03-11T17:09:21.788652+01:00",
                    "disabled_at": null,
                    "options": {
                        "choices": [
                            "Waiting time was too long",
                            "The park was difficult to navigate",
                            "Staff assistance was not sufficient",
                            "Some attractions were unavailable",
                            "The visit felt disorganized"
                        ],
                        "skippable_label": "Skip this question",
                        "skippable": true
                    }
                },
                {
                    "id": "158yQm678w",
                    "triggers": [4, 5],
                    "title": "What worked best during your visit?",
                    "enabled": true,
                    "type": "multiple_answers",
                    "enabled_at": "2026-03-11T17:09:21.791675+01:00",
                    "disabled_at": null,
                    "options": {
                        "choices": [
                            "Smooth visitor flow",
                            "Clear directions and signage",
                            "Friendly and helpful staff",
                            "Good attraction availability",
                            "Well-organized experience"
                        ],
                        "skippable_label": "Skip this question",
                        "skippable": true
                    }
                }
            ]
        },
        {
            "id": "bJdY1E6OdR",
            "position": 3,
            "title": "How did you feel when you saw the dinosaurs for the first time?",
            "enabled": true,
            "type": "emoji",
            "enabled_at": "2026-03-11T17:09:21.794878+01:00",
            "disabled_at": null,
            "options": {
                "labels": [
                    "Not impressed at all",
                    "Slightly impressed",
                    "Quite impressed",
                    "Very impressed"
                ]
            },
            "sub_questions": []
        },
        {
            "id": "ELxjqVoV4K",
            "position": 4,
            "title": "Did you feel safe during your visit to Jurassic Park?",
            "enabled": true,
            "type": "yesno",
            "enabled_at": "2026-03-11T17:09:21.797788+01:00",
            "disabled_at": null,
            "options": {},
            "sub_questions": []
        },
        {
            "id": "k6xmwOvKdj",
            "position": 5,
            "title": "What was the highlight of your visit to Jurassic Park?",
            "enabled": true,
            "type": "choices",
            "enabled_at": "2026-03-11T17:09:21.800797+01:00",
            "disabled_at": null,
            "options": {
                "choices": [
                    "The T-Rex encounter",
                    "The raptor zone",
                    "The dinosaur safari tour"
                ]
            },
            "sub_questions": []
        },
        {
            "id": "OJ85go5n4w",
            "position": 6,
            "title": "Which parts of your Jurassic Park visit did you enjoy the most?",
            "enabled": true,
            "type": "multiple_answers",
            "enabled_at": "2026-03-11T17:09:21.803983+01:00",
            "disabled_at": null,
            "options": {
                "choices": [
                    "Seeing the dinosaurs up close",
                    "The guided tour",
                    "The interactive attractions",
                    "The gift shop",
                    "The live shows or demonstrations",
                    "The adventure and excitement"
                ]
            },
            "sub_questions": []
        },
        {
            "id": "Zmxo3QWqxj",
            "position": 7,
            "title": "What could we improve to make your next visit to Jurassic Park even better?",
            "enabled": true,
            "type": "text",
            "enabled_at": "2026-03-11T17:09:21.806988+01:00",
            "disabled_at": null,
            "options": {
                "skippable_label": "Skip this question",
                "skippable": true
            },
            "sub_questions": []
        },
        {
            "id": "Q54E5XpK4y",
            "position": 8,
            "title": "How likely are you to recommend Jurassic Park to a friend or family member?",
            "enabled": true,
            "type": "nps",
            "enabled_at": "2026-03-11T17:09:21.810043+01:00",
            "disabled_at": null,
            "options": {
                "alert_limit": 6
            },
            "sub_questions": []
        }
    ],
    "places": "https://api.goodays.co/v2/surveys/yLdLGNm8j1/places",
    "responses": "https://api.goodays.co/v2/surveys/yLdLGNm8j1/responses"
}

2. Complete Response API Payload Example

This JSON shows the output returned by the Response API. This single, comprehensive example demonstrates:

An alert_triggered status (due to a low CSAT score of 2).
A mother-daughter conditional question (the low CSAT score triggered the "main issue" question).
Included metadata (message, user, context, and place blocks).

{
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "6xmpPLON4j",
            "token": "f1f1056a9fac71ca44f7a0267f1833dc5540f1ea0a6d48590ca18d24b69b8b39",
            "created_date": "2026-03-12T10:59:52.108239+01:00",
            "updated_date": "2026-03-12T10:59:52.243673+01:00",
            "source": "widget",
            "survey": {
                "id": "yLdLGNm8j1",
                "slug": "jp_post_visit",
                "label": "Jurassic Park - Post Visit",
                "enabled": true,
                "detail_url": "https://api.goodays.co/v2/surveys/yLdLGNm8j1"
            },
            "answers": [
                {
                    "id": "D82bQgWW38",
                    "value": 2,
                    "question": {
                        "id": "nlxDYWQJ8M",
                        "title": "How would you rate your overall experience at Jurassic Park?",
                        "type": "stars",
                        "enabled": true
                    }
                },
                {
                    "id": "Ed7k21bnLd",
                    "value": 2,
                    "question": {
                        "id": "yLdLYQpm4j",
                        "title": "How satisfied were you with the organization and flow of your visit to Jurassic Park?",
                        "type": "csat",
                        "enabled": true
                    }
                },
                {
                    "id": "Y4WJMZb0Jd",
                    "value": [
                        "Some attractions were unavailable",
                        "Waiting time was too long"
                    ],
                    "question": {
                        "id": "pe8NzlDM8j",
                        "title": "What was the main issue during your visit?",
                        "type": "multiple_answers",
                        "enabled": true
                    }
                },
                {
                    "id": "vdOp5zbjM4",
                    "value": "Non",
                    "question": {
                        "id": "ELxjqVoV4K",
                        "title": "Did you feel safe during your visit to Jurassic Park?",
                        "type": "yesno",
                        "enabled": true
                    }
                },
                {
                    "id": "mxomv9GaNd",
                    "value": 4,
                    "question": {
                        "id": "Q54E5XpK4y",
                        "title": "How likely are you to recommend Jurassic Park to a friend or family member?",
                        "type": "nps",
                        "enabled": true
                    }
                }
            ],
            "message": {
                "id": "vdANkQ1W4j",
                "created_date": "2026-03-12T11:00:48.653910+01:00",
                "type": "Problem",
                "content": "The waiting time for the T-Rex enclosure was unacceptable, and the staff seemed overwhelmed.",
                "attachment": null,
                "sender": {
                    "email": "[email protected]",
                    "first_name": "Alan",
                    "last_name": "Grant"
                }
            },
            "reply": null,
            "user": {
                "email": "[email protected]",
                "first_name": "Alan",
                "last_name": "Grant",
                "opt_in": {
                    "newsletter": false,
                    "email": true,
                    "sms": false,
                    "custom": false
                }
            },
            "context": {
                "email": "[email protected]",
                "phone": "0600000000",
                "crm_id": "VIP-9932",
                "cz_tag": "jp_post_visit",
                "last_name": "Grant",
                "first_name": "Alan"
            },
            "place": {
                "id": "EexqBnL58Y",
                "partner_id": "park-isla-nublar",
                "name": "Jurassic Park - Isla Nublar",
                "enabled": true,
                "detail_url": "https://api.goodays.co/v2/places/EexqBnL58Y"
            },
            "delegated_to": null,
            "attached_messages": [],
            "state": "open",
            "thread": "y8VZ06lL8G",
            "actions": {
                "reply": "https://api.goodays.co/api/v2/responses/6xmpPLON4j/reply",
                "spam": "https://api.goodays.co/api/v2/responses/6xmpPLON4j/spam",
                "close": "https://api.goodays.co/api/v2/responses/6xmpPLON4j/close"
            },
            "alert_triggered": true
        }
    ]
}

Survey Question Types & Structures

Core Question Object Structure

Supported Question Types

1. Stars Rating (stars)

2. Customer Satisfaction (csat)

3. Net Promoter Score (nps)

4. Open-ended Text (text)

5. Single Choice (choices)

6. Multiple Choice (multiple_answers)

7. Emoji Sentiment (emoji)

8. Boolean Yes/No (yesno)

9. Customer Effort Score (ces)

Advanced Behaviors

Conditional Logic (Mother-Daughter Questions)

Skippable Questions

Handling Alerts (alert_triggered)

Appendix: Complete JSON Examples

1. Complete Survey Structure Example

2. Complete Response API Payload Example

1. Stars Rating (`stars`)

2. Customer Satisfaction (`csat`)

3. Net Promoter Score (`nps`)

4. Open-ended Text (`text`)

5. Single Choice (`choices`)

6. Multiple Choice (`multiple_answers`)

7. Emoji Sentiment (`emoji`)

8. Boolean Yes/No (`yesno`)

9. Customer Effort Score (`ces`)

Handling Alerts (`alert_triggered`)