> ## Documentation Index
> Fetch the complete documentation index at: https://developers.respondent.io/llms.txt
> Use this file to discover all available pages before exploring further.

> List all screener responses for a project with filtering and pagination. Use query parameters to filter by status, qualification state, or date range.

# List screener responses

## Typical workflow

<Steps>
  <Step title="List responses">
    Retrieve screener responses and review participant answers.
  </Step>

  <Step title="Qualify or disqualify">
    Use [Qualify Participant](/screener-responses/qualify-participant) to approve or reject based on screener answers.
  </Step>

  <Step title="Invite qualified participants">
    Send invitations via [Invite Participant](/screener-responses/invite-participant).
  </Step>

  <Step title="Mark attendance and pay">
    After the session, use [Mark as Attended](/screener-responses/mark-as-attended) to trigger payment.
  </Step>
</Steps>


## OpenAPI

````yaml get /v1/projects/{projectId}/screener-responses
openapi: 3.0.0
info:
  title: Partner API
  description: Public API for partner integrations
  version: '1.0'
  contact: {}
servers:
  - url: https://api-staging.respondent.io
security: []
tags: []
paths:
  /v1/projects/{projectId}/screener-responses:
    get:
      tags:
        - screener-responses
      summary: List screener responses
      operationId: ScreenerResponsesController_findAll
      parameters:
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
        - name: x-api-secret
          in: header
          required: true
          schema:
            type: string
        - name: projectId
          required: true
          in: path
          schema:
            type: string
        - name: page
          required: false
          in: query
          description: Specifies which page of results to return
          schema:
            type: number
            default: 1
        - name: pageSize
          required: false
          in: query
          description: Number of records to return per page
          schema:
            type: number
            default: 50
        - name: includeCount
          required: false
          in: query
          description: If true, includes the total count of records
          schema:
            type: boolean
            default: false
        - name: hidden
          required: false
          in: query
          schema:
            type: boolean
            default: false
        - name: status
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/ScreenerResponseStatus'
        - name: statuses
          required: false
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ScreenerResponseStatus'
        - name: qualified
          required: false
          in: query
          schema:
            type: boolean
        - name: favorite
          required: false
          in: query
          schema:
            type: boolean
        - name: visibilityStatus
          required: false
          in: query
          schema:
            $ref: '#/components/schemas/ScreenerResponseVisibilityStatus'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreenerResponsesPaginatedDto'
components:
  schemas:
    ScreenerResponseStatus:
      type: string
      enum:
        - PENDING
        - INVITED
        - SCHEDULED
        - ATTENDED
        - NOSHOW
        - INVALIDRESPONSE
        - REJECTEDQUALITY
        - PAID
        - CANCELLED
    ScreenerResponseVisibilityStatus:
      type: string
      default: VISIBLE
      enum:
        - DISMISSED
        - VISIBLE
        - ONHOLD
    ScreenerResponsesPaginatedDto:
      type: object
      properties:
        totalResults:
          type: number
          description: >-
            The total number of results possible, which is only provided in the
            response when `includeCount` is passed as `true` within a request.
        page:
          type: number
          default: 1
        pageSize:
          type: number
          default: 50
        results:
          type: array
          items:
            $ref: '#/components/schemas/ScreenerResponse'
      required:
        - page
        - pageSize
    ScreenerResponse:
      type: object
      properties:
        qualified:
          type: boolean
        qualifiedPendingIdVerification:
          type: boolean
          description: >-
            - This property is set to `true` (with `qualified` set to `false`)
            if the participant has qualified based on their responses to the
            screener, but is in the process of verifying their identity.

            - Once the participant has completed ID verification,
            `qualifiedPendingIdVerification` will be set to false.
              - If the verification was successful, `qualified` will be set to `true`.
              - If the verification failed, `qualified` will remain set to `false` unless they were manually qualified through the qualification endpoint
            (`PATCH
            /projects/{projectId}/screener-responses/{screenerResponseId}/qualify`).
        percentage:
          type: number
        status:
          $ref: '#/components/schemas/ScreenerResponseStatus'
        favorite:
          type: boolean
        hidden:
          type: boolean
        responses:
          type: array
          items:
            $ref: '#/components/schemas/ScreenerResponseAnswer'
        totalTime:
          type: number
        isNew:
          type: boolean
        inviteSentAt:
          format: date-time
          type: string
        scheduledAt:
          format: date-time
          type: string
        statusUpdatedAt:
          format: date-time
          type: string
        ndaUrl:
          type: string
        ndaAgree:
          type: boolean
        project:
          $ref: '#/components/schemas/ScreenerResponseProject'
        profile:
          $ref: '#/components/schemas/ScreenerResponseProfile'
        matching:
          $ref: '#/components/schemas/ScreenerResponseMatching'
        externalProject:
          $ref: '#/components/schemas/ExternalProject'
        invitation:
          $ref: '#/components/schemas/ScreenerResponseInvitation'
        actor:
          $ref: '#/components/schemas/Actor'
        reason:
          $ref: '#/components/schemas/ParticipantCancellationReason'
        shortNoticeCancel:
          type: boolean
        message:
          type: string
        rejection:
          $ref: '#/components/schemas/Rejection'
        visibility:
          description: >-
            The visibility status of the screener response.

            If a screener response is visible, it can be interacted with
            (invited etc).

            If a screener response is not visible, it cannot be interacted with.

            A screener may be hidden for various reasons, and a screener can
            change from visible

            to not visible at any time if a participant or screener is found to
            be untrustworthy.

            There is a webhook that will notify the client when a screener
            response changes visibility.
          allOf:
            - $ref: '#/components/schemas/ScreenerResponseVisibility'
        createdAt:
          format: date-time
          type: string
        task:
          $ref: '#/components/schemas/ScreenerResponseTask'
        id:
          type: string
        projectId:
          type: string
        userId:
          type: string
      required:
        - qualified
        - percentage
        - status
        - responses
        - totalTime
        - matching
        - visibility
        - id
        - projectId
        - userId
    ScreenerResponseAnswer:
      type: object
      properties:
        questionId:
          type: string
        questionText:
          type: string
        order:
          type: number
        type:
          type: string
        questionType:
          $ref: '#/components/schemas/QuestionType'
        answers:
          type: array
          items:
            $ref: '#/components/schemas/ScreenerQuestionAnswerValue'
        qualify:
          type: boolean
        skipped:
          type: boolean
          description: >-
            Only present when the `screener-responses-include-skipped-questions`
            feature flag is enabled for the calling organization (default OFF).
            `true` when the participant did not answer this question — either
            because they chose to skip an optional question (`skippedBy: user`)
            or because skip-logic on a previous question routed them past it
            (`skippedBy: skipLogic`).
        skippedBy:
          type: string
          enum:
            - user
            - skipLogic
          description: >-
            Only present when the `screener-responses-include-skipped-questions`
            feature flag is enabled for the calling organization (default OFF).
            `user` means the participant saw the question and chose to skip it;
            `skipLogic` means the participant never saw it because skip-logic on
            a previous question routed past it. Absent on items where `skipped`
            is not `true`.
        shown:
          type: boolean
          description: >-
            Only present when the `screener-responses-include-skipped-questions`
            feature flag is enabled for the calling organization (default OFF).
            `true` for answered questions and user-skipped questions (i.e. the
            participant saw the question); `false` for skip-logic-skipped
            questions (the participant never saw it).
      required:
        - questionId
        - questionText
        - type
        - questionType
        - answers
        - qualify
    ScreenerResponseProject:
      type: object
      properties:
        name:
          type: string
        incentive:
          type: number
        id:
          type: string
        organizationId:
          type: string
        teamId:
          type: string
      required:
        - name
        - incentive
        - id
        - organizationId
        - teamId
    ScreenerResponseProfile:
      type: object
      properties:
        id:
          type: string
          format: ObjectId
        userId:
          type: string
          format: ObjectId
        firstName:
          type: string
        lastName:
          type: string
        picture:
          type: string
          nullable: true
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SimpleSkill'
      required:
        - id
        - userId
        - firstName
        - lastName
        - skills
    ScreenerResponseMatching:
      type: object
      properties:
        isGenderMatch:
          type: boolean
        isAgeMatch:
          type: boolean
        isEthnicityMatch:
          type: boolean
        isEducationMatch:
          type: boolean
        questionsQualified:
          type: boolean
        isLocationMatch:
          type: boolean
        isIndustryMatch:
          type: boolean
        isJobTitleMatch:
          type: boolean
        isHouseholdIncomeMatch:
          type: boolean
        isCompanySizeMatch:
          type: boolean
        isTopicsMatch:
          type: boolean
      required:
        - isGenderMatch
        - isAgeMatch
        - isEthnicityMatch
        - isEducationMatch
        - questionsQualified
        - isLocationMatch
        - isIndustryMatch
        - isJobTitleMatch
        - isHouseholdIncomeMatch
        - isCompanySizeMatch
    ExternalProject:
      type: object
      properties:
        researcherId:
          type: string
        bookingUrl:
          type: string
        meetingCancelLink:
          type: string
          description: Link to cancel a meeting. If not set, bookingLink will be used.
        bookedDate:
          format: date-time
          type: string
        timezone:
          type: string
          description: 'IANA timezone. Example: ''America/New_York'''
      required:
        - researcherId
    ScreenerResponseInvitation:
      type: object
      properties:
        id:
          type: string
          format: ObjectId
        remoteCommunicationDetails:
          type: string
        event:
          $ref: '#/components/schemas/InvitationEvent'
        message:
          type: string
          description: This will override the special instructions from the project.
          default: null
        videoProvider:
          $ref: '#/components/schemas/InvitationVideoProvider'
      required:
        - id
    Actor:
      type: string
      enum:
        - researcher
        - respondent
        - admin
    ParticipantCancellationReason:
      type: string
      enum:
        - time
        - final
    Rejection:
      type: object
      properties:
        message:
          type: string
        rejectedAt:
          format: date-time
          type: string
      required:
        - message
        - rejectedAt
    ScreenerResponseVisibility:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ScreenerResponseVisibilityStatus'
      required:
        - status
    ScreenerResponseTask:
      type: object
      properties:
        completedAt:
          type: string
          description: >-
            Timestamp when the task was completed.

            This field is automatically set when participants access the
            project's completionUrl.
    QuestionType:
      type: string
      enum:
        - radio
        - multiLineTextbox
        - checkbox
        - singleLineTextbox
        - numericBox
        - sliderScale
        - fileUpload
    ScreenerQuestionAnswerValue:
      type: object
      properties:
        id:
          type: string
        uid:
          type: string
        text:
          type: string
        answerValue:
          type: number
        goToQuestionUid:
          type: string
          nullable: true
        isOther:
          type: boolean
        other:
          type: string
      required:
        - id
        - uid
        - text
        - answerValue
    SimpleSkill:
      type: object
      properties:
        id:
          type: string
          format: ObjectId
        name:
          type: string
        slug:
          type: string
        validated:
          type: boolean
          default: false
        type:
          type: string
          default: skill
      required:
        - id
        - name
        - slug
        - validated
        - type
    InvitationEvent:
      type: object
      properties:
        uid:
          type: string
      required:
        - uid
    InvitationVideoProvider:
      type: object
      properties:
        loginProviderId:
          type: string
        providerKey:
          type: string
          enum:
            - zoom
        userId:
          type: string
      required:
        - loginProviderId
        - providerKey
        - userId

````