Response formatting

When collecting screener responses there may be one or multiple responses but generally the content of each response has a predictable set of information returned

Basic Screener response

GET: /v1/projects/{projectId}/screener-responses The example below shows a screener-questions POST and subsequent screener-responses GET. The response itself has information relating to the answered questions themselves as well as the participant. Most of the participant information can be found via a second call using the profile ID.

Answer shapes by question type

Each item in responses[] has an answers field that is always an array. The type of the array’s elements depends on questionType:

`questionType`	`answers` contains	Example
`radio`	A single answer object	`[{ "id": "…", "uid": "…", "text": "West Coast", "answerValue": 1 }]`
`checkbox`	One answer object per selected option	`[{ …option 1… }, { …option 2… }]`
`singleLineTextbox`	A single string with the participant’s raw input	`["Green"]`
`multiLineTextbox`	A single string with the participant’s raw input	`["My favorite hobby is riding motorcycles."]`
`numericBox`	A single string (numeric input is not converted to a number)	`["36"]`
`sliderScale`	A single string with the selected value	`["9"]`
`rank`	Empty — see the `ranking` field instead	`[]`
`matrix`	Empty — see the `selections` field instead	`[]`

Responses recorded before 2024 may contain bare numbers instead of strings for numericBox/sliderScale answers. Parsers should accept both. When displaying the responses section of the screener-response it is recommended to share:

Time the participant took to complete the screener
"totalTime":
The incentive the participant took the screener at
- "project.incentive":
Time screener was completed
- "createdAt":
Question, response, and qualify status
- "questionText":
- "text":
- "qualify":

"projectID": "PROJECT_ID"
{
  "questionType": "radio",
  "text": "What is your favorite coastline in the United States?",
  "answers": [
    {
      "text": "East Coast",
      "answerValue": 2
    },
    {
      "text": "West Coast",
      "answerValue": 1
    },
    {
      "isOther": true,
      "text": "Other",
      "answerValue": 2
    }
  ],
  "skipLogic": false,
  "includeOtherOption": true,
  "isRequired": true
},
{
  "questionType": "checkbox",
  "text": "What animals would you like to spend time with?",
  "answers": [
    {
      "text": "Cat",
      "answerValue": 1
    },
    {
      "text": "Dog",
      "answerValue": 1
    },
    {
      "text": "Giraffe",
      "answerValue": 1
    },
    {
      "text": "Pineapple",
      "answerValue": 3
    }
  ],
  "isRequired": true,
  "skipLogic": false,
  "includeOtherOption": false
},
{
  "questionType": "multiLineTextbox",
  "text": "In your own words, tell us what your favorite hobby is.",
  "skipLogic": false,
  "isRequired": true
},
{
  "questionType": "singleLineTextbox",
  "text": "What is your favorite color?",
  "skipLogic": false,
  "isRequired": true
},
{
  "questionType": "numericBox",
  "text": "How old are you?",
  "skipLogic": false,
  "isRequired": true
},
{
  "questionType": "sliderScale",
  "text": "On a scale from 1 to 10 how confident are you building an API?",
  "isRequired": true,
  "skipLogic": false,
  "minValue": 1,
  "maxValue": 10,
  "step": 1
}

{
            "id": "RESPONSE_ID",
            "projectId": "PROJECT_ID",
            "qualified": true,
            "status": "PENDING",
            "favorite": false,
            "hidden": false,
            "responses": [
                {
                    "questionId": "6526e85f08fa017ec030ec93",
                    "questionText": "What is your favorite coastline in the United States?",
                    "order": 0,
                    "type": "screener",
                    "questionType": "radio",
                    "answers": [
                        {
                            "id": "6526e85f08fa017ec030ec94",
                            "uid": "b80c8be4-5abc-45c0-a92b-24552095ac9d",
                            "text": "West Coast",
                            "answerValue": 1,
                            "goToQuestionUid": null
                        }
                    ],
                    "qualify": true
                },
                {
                    "questionId": "6526e85f08fa017ec030ec96",
                    "questionText": "What animals would you like to spend time with?",
                    "order": 1,
                    "type": "screener",
                    "questionType": "checkbox",
                    "qualify": true,
                    "answers": [
                        {
                            "id": "6526e85f08fa017ec030ec98",
                            "uid": "c84ba5eb-a487-43b0-8196-aa5f538f4bc9",
                            "text": "Pineapple",
                            "answerValue": 3,
                            "goToQuestionUid": null,
                            "checked": true
                        }
                    ]
                },
                {
                    "questionId": "6526e85f08fa017ec030ec9a",
                    "questionText": "In your own words, tell us what your favorite hobby is.",
                    "order": 2,
                    "type": "screener",
                    "questionType": "multiLineTextbox",
                    "answers": ["My favorite hobby is riding motorcycles."],
                    "qualify": true
                },
                {
                    "questionId": "6526e85f08fa017ec030ec9b",
                    "questionText": "What is your favorite color?",
                    "order": 3,
                    "type": "screener",
                    "questionType": "singleLineTextbox",
                    "answers": ["Green"],
                    "qualify": true
                },
                {
                    "questionId": "6526e85f08fa017ec030ec9c",
                    "questionText": "How old are you?",
                    "order": 4,
                    "type": "screener",
                    "questionType": "numericBox",
                    "answers": ["36"],
                    "qualify": true
                },
                {
                    "questionId": "6526e85f08fa017ec030ec9d",
                    "questionText": "On a scale from 1 to 10 how confident are you building an API?",
                    "order": 5,
                    "type": "screener",
                    "questionType": "sliderScale",
                    "answers": ["9"],
                    "qualify": true
                }
            ],
            "totalTime": 33,
            "isNew": false,
            "visibility": {
                "name": "VISIBLE",
                "status": "VISIBLE",
                "code": "OK"
            },
            "statusUpdatedAt": null,
            "project": {
                "id": "PROJECT_ID",
                "name": "Test Screener Answer Values",
                "incentive": 125,
                "organizationId": "ORG_ID",
                "teamId": "TEAM_ID"
            },
            "profile": {
                "id": "PROFILE_ID",
                "firstName": "Bob",
                "lastName": "H",
                "skills": [
                    {
                        "createdAt": "2023-10-11T18:27:24.260Z",
                        "validated": true,
                        "type": "certification",
                        "count": 0,
                        "slug": "typescript",
                        "id": "SKILL_ID",
                        "name": "TypeScript"
                    }
                ]
            }
        }

Viewing the profile

/v1/profiles/{profileId}

{
  "userId": "string",
  "companySize": "selfemployed",
  "gender": "male",
  "educationLevel": "somehighschool",
  "ethnicity": "americanindianalaskannative",
  "householdIncome": "<30000",
  "firstName": "Bob",
  "lastInitial": "H",
  "jobTitle": "PM",
  "jobFunctions": [
        "informationTechnology"
  ],
  "linkedinUrl": "URL",
  "skills": [
    {
    
        "createdAt": "2023-10-11T18:27:24.260Z",
        "validated": true,
        "type": "certification",
        "count": 0,
        "slug": "typescript",
        "id": "SKILL_ID",
        "name": "TypeScript"
    }
  ],
  "isEmailVerified": true,
  "location": {
  "country": "US",
        "location": {
          "longitude": 42.22788,
          "latitude": -71.191113
        },
        "city": "Boston",
        "state": "MA",
  },
  "age": "string",
  "socialLinks": {},
  "industry": [
    "string"
  ],
  "seniorityLevel": "senior",
  "id": "string",
  "createdAt": "2023-10-11T18:27:24.260Z",
  "updatedAt": "2023-10-15T13:24:35.260Z"
}

Understanding qualified responses

"qualified": true, implies:

NDA is agree to if present
100% percentage on screener questions
Matched on location, age, gender, education, and ethnicity

The “End Of Survey” sentinel

Every screener’s question list ends with an auto-generated sentinel entry marked isEnd: true:

{
    "id": "6864ea79744b87a65743b880",
    "uid": null,
    "text": "End Of Survey",
    "isEnd": true,
    "answers": []
}

You will see it as the last element of screenerQuestions on the project payload and on the screener-questions endpoints. It is always present and always last, but it is not a real question: it has no questionType, its uid and order are null or absent, participants never answer it, and it never appears in screener-response responses[] — every item there corresponds to a question the participant actually answered (or, with the skipped-questions option below, explicitly skipped). Skip the sentinel when rendering or counting questions. isEnd is present on every screener question — false on real questions, true on this sentinel — so you can discriminate on it directly rather than treating an absent field as false. Note that the sentinel’s answers field, unlike a real question’s, is sometimes absent rather than an empty array, so do not call .length on it without checking. Older versions of this API also appended an “End Of Survey” trailer entry to responses[] itself (with null values for order and answers), and earlier versions of this guide showed it in the example payload. The current API never does; no special handling is required in response parsing.

Skipped questions in `responses[]`

By default, questions that a participant did not answer (because they were skipped over by skip logic, or because the participant chose to skip an optional question) are omitted from the responses[] array. Organizations that opt in to including skipped questions in screener responses (contact Respondent to enable) receive an entry for every screener question, with skipped questions marked explicitly. Each item in responses[] then includes:

Field	Type	Description
`skipped`	`boolean`	`true` if the participant did not provide an answer to this question. Absent or `false` for answered questions.
`skippedBy`	`'user' \| 'skipLogic'`	Why the question was skipped. `'user'` means the participant chose to skip an optional question; `'skipLogic'` means skip logic on a previous answer jumped over this question. Present only when `skipped` is `true`.
`shown`	`boolean`	`true` if the question was displayed to the participant. Equivalent to `!skipped \|\| skippedBy === 'user'` — i.e. answered questions and user-skipped optional questions were shown; skip-logic-skipped questions were not.

Example skipped entries:

{
  "questionId": "6526e85f08fa017ec030ec9b",
  "questionText": "What is your favorite color?",
  "order": 3,
  "type": "screener",
  "questionType": "singleLineTextbox",
  "answers": [],
  "qualify": true,
  "skipped": true,
  "skippedBy": "user",
  "shown": true
},
{
  "questionId": "6526e85f08fa017ec030ec9c",
  "questionText": "How old are you?",
  "order": 4,
  "type": "screener",
  "questionType": "numericBox",
  "answers": [],
  "qualify": true,
  "skipped": true,
  "skippedBy": "skipLogic",
  "shown": false
}

Skipped entries still carry answers, as an empty array — the field is present on every item in responses[].

Getting started

Projects

Screeners and Responses

Messaging

Webhooks

Guides

Collecting responses

Response formatting

Basic Screener response

Answer shapes by question type

Viewing the profile

Understanding qualified responses

The “End Of Survey” sentinel

Skipped questions in `responses[]`

​Response formatting

​Basic Screener response

​Answer shapes by question type

​Viewing the profile

​Understanding qualified responses

​The “End Of Survey” sentinel

​Skipped questions in responses[]

Response formatting

Basic Screener response

Answer shapes by question type

Viewing the profile

Understanding qualified responses

The “End Of Survey” sentinel

Skipped questions in `responses[]`