Endpoints to retrieve custom survey information from within Vitally using the REST API.

The Custom Survey object

Attributes	Description	Editable?
id	Vitally's unique ID for the custom survey response	No
surveyId	Vitally's unique ID for the survey	No
organizationId	Vitally ID for the organization this Survey belongs to (if applicable)	No
userID	The ID for the User that has responded to the survey	No
title	The title for the question	No
body	The description given to the survey
createdAt	The date/time when the custom survey was created	No
updatedAt	The date/time when the custom survey was updated	No
respondedAt	When the response to the survey was captured	No

Replace {subdomain} in the endpoints below with your Vitally subdomain.

You can find your subdomain in the URL used to log into Vitally (i.e., https://yoursubdomain.vitally.io

The Survey Questions Object

Attributes	Description	Editable?
id	The ID for the survey response to the question	No
questionId	The ID for the survey question	No
data.type	The type of survey question (e.g., string, number, array, etc.)	No
data.value	The value that has been submitted for the survey question	No

For singleSelect, multiSelect, and emojiSelect questions, data.value is stored as a raw option ID (a single ID for singleSelect/emojiSelect, an array of IDs for multiSelect). To resolve it into the option's display label, match it against the options array returned by the Survey Question Details endpoint and use the corresponding textValue.

Get Survey Responses for a Survey GET

Get all survey responses for a specific survey

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/surveys/{surveyId}/responses

EU Data Center:

https://rest.vitally-eu.io/resources/surveys/{surveyId}/responses

The survey ID can be obtained from within the URL in-app when opening the survey in Vitally under Settings > Surveys > Custom Surveys > select the desired survey

https://{subdomain}.vitally.io/settings/surveys/{surveyId}

Example Request

GET https://{subdomain}.rest.vitally.io/resources/surveys/209a9512-8b27-4d29-b2d3-082588519940/responses

Example Response

{
    "next": null,
    "data": [
        {
            "id": "b72e4b4a-f443-42f0-9264-c3e6f6fb9def",
            "surveyId": "209a9512-8b27-4d29-b2d3-082588519940",
            "createdAt": "2025-08-18T20:47:30.186Z",
            "updatedAt": "2025-08-18T20:47:30.186Z",
            "respondedAt": "2025-08-18T20:47:30.186Z",
            "userId": "f3d7b6d5-5058-405e-bba5-8da83bdf2276",
            "questionResponses": [
                {
                    "id": "82d76f8d-aaa4-48f8-9ca2-fb66e6ad4d1f",
                    "questionId": "9d90b9d1-6751-4bd7-90cb-fc3166556aba",
                    "data": {
                        "type": "number",
                        "value": 10
                    }
                },
                {
                    "id": "7ad4ef7d-ea3e-4955-a179-d4684362bc3d",
                    "questionId": "38237727-b6af-42e2-9d87-f0f0f28926e1",
                    "data": {
                        "type": "string",
                        "value": "d68f2f78-8eeb-4bde-9319-2bc49d4538d5"
                    }
                },
                {
                    "id": "eec8b34e-98d3-4cc2-a5cc-cd34861c9af3",
                    "questionId": "c7399db1-2b05-4b4e-8194-38fdb1c27d41",
                    "data": {
                        "type": "string",
                        "value": "Love it!"
                    }
                }
            ]
        },
        ...
    ]
}

Get Survey Response by Response ID GET

Retrieve a specific survey response with its associated answers.

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/surveyResponses/{responseId}

EU Data Center:

https://rest.vitally-eu.io/resources/surveyResponses/{responseId}

The responseId used in this request is the survey response's unique identifier. Each survey response has a unique ID. You can retrieve it from the id property in the results returned by the Get Survey Responses for a Survey endpoint.

Example Request

GET https://{subdomain].rest.vitally.io/resources/surveyResponses/b72e4b4a-f443-42f0-9264-c3e6f6fb9def

Example Response

{
    "data": {
        "id": "b72e4b4a-f443-42f0-9264-c3e6f6fb9def",
        "surveyId": "209a9512-8b27-4d29-b2d3-082588519940",
        "createdAt": "2025-08-18T20:47:30.186Z",
        "updatedAt": "2025-08-18T20:47:30.186Z",
        "respondedAt": "2025-08-18T20:47:30.186Z",
        "userId": "f3d7b6d5-5058-405e-bba5-8da83bdf2276",
        "questionResponses": [
            {
                "id": "82d76f8d-aaa4-48f8-9ca2-fb66e6ad4d1f",
                "questionId": "9d90b9d1-6751-4bd7-90cb-fc3166556aba",
                "data": {
                    "type": "number",
                    "value": 10
                }
            },
            {
                "id": "7ad4ef7d-ea3e-4955-a179-d4684362bc3d",
                "questionId": "38237727-b6af-42e2-9d87-f0f0f28926e1",
                "data": {
                    "type": "string",
                    "value": "d68f2f78-8eeb-4bde-9319-2bc49d4538d5"
                }
            },
            {
                "id": "eec8b34e-98d3-4cc2-a5cc-cd34861c9af3",
                "questionId": "c7399db1-2b05-4b4e-8194-38fdb1c27d41",
                "data": {
                    "type": "string",
                    "value": "Love it!"
                }
            }
        ]
    }
}

Survey Question Details GET

Retrieve metadata about a specific survey question.

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/surveyQuestions/{questionId}

EU Data Center:

https://rest.vitally-eu.io/resources/surveyQuestions/{questionId}

Question IDs can be obtained in the questionId property within the returned response when running the GET Survey Responses endpoint.

Example Request

GET https://{subdomain].rest.vitally.io/resources/surveyQuestion/f129305b-f9b7-4bb9-8c22-9cd3762a7c8a

Example Response

{
    "data": {
        "id": "c7399db1-2b05-4b4e-8194-38fdb1c27d41",
        "surveyId": "209a9512-8b27-4d29-b2d3-082588519940",
        "title": "Platform Feedback",
        "body": "How are you liking the platform?",
        "isRequired": false,
        "createdAt": "2024-04-25T14:06:08.089Z",
        "updatedAt": "2024-08-16T08:22:32.774Z",
        "type": "textLong",
    }
}

For singleSelect, multiSelect, and emojiSelect questions, the response also includes an options array. This field is present only for select-backed question types.

Attributes	Description	Editable?
id	Vitally's unique ID for the option	No
createdAt	The date/time the option was created	No
updatedAt	The date/time the option was last updated	No
textValue	The option's display label	No
emojiValue	The option's emoji, if the question uses an emoji scale	No

Example Response (select-backed question)

{
    "data": {
        "id": "c7399db1-2b05-4b4e-8194-38fdb1c27d41",
        "surveyId": "209a9512-8b27-4d29-b2d3-082588519940",
        "title": "How satisfied are you with our service?",
        "body": "",
        "isRequired": false,
        "createdAt": "2024-04-25T14:06:08.089Z",
        "updatedAt": "2024-08-16T08:22:32.774Z",
        "type": "singleSelect",
        "options": [
            {
                "id": "e8688090-73fe-4a7b-8f6e-49ea3d88a71e",
                "createdAt": "2024-04-25T14:06:08.089Z",
                "updatedAt": "2024-04-25T14:06:08.089Z",
                "textValue": "Very satisfied",
                "emojiValue": null
            },
            {
                "id": "90174b82-df55-40fd-95c6-18701d7fed9c",
                "createdAt": "2024-04-25T14:06:08.089Z",
                "updatedAt": "2024-04-25T14:06:08.089Z",
                "textValue": "Moderately satisfied",
                "emojiValue": null
            }
        ]
    }
}

REST API: Custom Surveys

The Custom Survey object

The Survey Questions Object

Get Survey Responses for a Survey GET

Get Survey Response by Response ID GET

Survey Question Details GET