> ## Documentation Index > Fetch the complete documentation index at: https://docs.rallyuxr.com/llms.txt > Use this file to discover all available pages before exploring further. # Replace a study's screener > Completely replace (upsert) the screener for a draft study. The entire screener configuration must be sent: question ids are regenerated on every call and omitted top-level properties reset to their defaults. Creates the screener (and enables the study's includeScreener flag) when the study has none. Only Rally screeners can be managed via the API. Not available for survey studies. ## OpenAPI ````yaml https://api.rallyuxr.com/api/openapi put /studies/{studyId}/screener openapi: 3.1.0 info: title: Rally UXR Developer Docs version: '1.0' servers: - url: https://api.rallyuxr.com/api/public/v1 security: - bearerAuth: [] tags: - name: Forms description: Operations on Forms in your workspace - name: People description: Operations on Person's stored in your workspace - name: Person Properties description: Operations on workspace level Person Properties - name: Populations description: Operations on Populations in your workspace - name: Segments description: Operations on Segments in your workspace - name: Studies description: Operations on Studies in your workspace - name: Participants description: Operations on Participants in studies - name: Participant Status Events description: Poll participant status-change events across your workspace - name: Study Status Events description: Poll-based access to study status-change events in your workspace - name: Screener description: Operations on a study's screener - name: Consent Submissions description: Operations on Consent Submissions for studies - name: Incentives description: Operations on Incentives in your workspace - name: Messages description: Operations on Message activities in your workspace - name: Imports description: Operations on Imports in your workspace - name: Users description: Operations on Workspace Users - name: Teams description: Operations on Teams in your workspace - name: Backfills description: >- Routes that can be used to backfill data into Rally. If you'd like access to these apis, please reach out to your Customer Success rep - name: Person description: Deprecated, use People paths: /studies/{studyId}/screener: put: tags: - Screener summary: Replace a study's screener description: >- Completely replace (upsert) the screener for a draft study. The entire screener configuration must be sent: question ids are regenerated on every call and omitted top-level properties reset to their defaults. Creates the screener (and enables the study's includeScreener flag) when the study has none. Only Rally screeners can be managed via the API. Not available for survey studies. parameters: - $ref: '#/components/parameters/StudyId' requestBody: content: application/json: schema: $ref: '#/components/schemas/ScreenerPutBody' responses: '200': description: The replaced screener headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ScreenerResponse' '400': description: >- Bad Request — JSON with field details for schema validation errors, plain text for domain rule violations content: application/json: schema: $ref: '#/components/schemas/BadRequestError' text/plain: schema: type: string example: Bad Request '401': description: Unauthorized headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: text/plain: schema: type: string example: Unauthorized '403': description: Forbidden headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: text/plain: schema: type: string example: Forbidden '404': description: Not Found content: text/plain: schema: type: string example: '{Resource} not found' '409': description: Conflict headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: text/plain: schema: type: string example: Study is not in draft status '429': description: Too Many Requests headers: Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: text/plain: schema: type: string example: Too Many Requests '500': description: Internal Server Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: text/plain: schema: type: string example: Internal Server Error security: - bearerAuth: [] components: parameters: StudyId: schema: $ref: '#/components/schemas/StudyId' required: true name: studyId in: path schemas: ScreenerPutBody: type: object properties: showSchedulerToQualified: type: boolean default: false description: >- Show the interview scheduler to respondents who qualify. Omitted values reset to false (full replace). qualifyByDefault: type: boolean default: false description: >- Qualify respondents unless a rule disqualifies them. Omitted values reset to false (full replace). questions: type: array items: $ref: '#/components/schemas/PutScreenerQuestion' minItems: 1 maxItems: 50 description: The ordered list of screener questions required: - questions additionalProperties: false description: >- The complete screener configuration. PUT fully replaces the existing screener: question ids are regenerated and omitted top-level properties reset to their defaults. ScreenerResponse: allOf: - $ref: '#/components/schemas/Screener' - type: object properties: questions: type: array items: $ref: '#/components/schemas/ScreenerQuestionResponse' description: The screener questions, in display order required: - questions description: A screener with its top-level properties and all questions BadRequestError: type: object properties: errors: type: array items: type: object properties: message: type: string path: type: array items: anyOf: - type: string - type: number required: - message - path required: - errors description: Error response for a bad request with details on what was invalid StudyId: type: string PutScreenerQuestion: oneOf: - $ref: '#/components/schemas/PutTemplateScreenerQuestion' - $ref: '#/components/schemas/PutSimpleScreenerQuestion' - $ref: '#/components/schemas/PutOptionScreenerQuestion' - $ref: '#/components/schemas/PutDropdownScreenerQuestion' - $ref: '#/components/schemas/PutMatrixScreenerQuestion' discriminator: propertyName: category mapping: template: $ref: '#/components/schemas/PutTemplateScreenerQuestion' simple: $ref: '#/components/schemas/PutSimpleScreenerQuestion' option: $ref: '#/components/schemas/PutOptionScreenerQuestion' dropdown: $ref: '#/components/schemas/PutDropdownScreenerQuestion' matrix: $ref: '#/components/schemas/PutMatrixScreenerQuestion' description: A single question to create, discriminated by category Screener: type: object properties: id: type: string description: The screener id workspaceId: type: string description: The workspace that owns the screener studyId: type: string description: The study the screener belongs to type: $ref: '#/components/schemas/ScreenerType' showSchedulerToQualified: type: boolean description: Whether the interview scheduler is shown to respondents who qualify qualifyByDefault: type: boolean description: Whether respondents qualify unless a rule disqualifies them externalSurveyId: type: string description: The id of the linked external survey, when the screener uses one surveyMonkeyCollectorId: type: string description: >- The SurveyMonkey collector id, when the screener uses a SurveyMonkey survey externalSurveySetupStatus: $ref: '#/components/schemas/ExternalSurveySetupStatus' externalSurveySetupErrorCode: type: string description: >- An error code describing why external survey setup failed, when applicable externalSurveySetupUpdatedAt: type: string format: date-time description: When the external survey setup status last changed (ISO 8601) customLinkUrl: type: string description: >- The custom link respondents use to take an externally hosted screener customLinkTokensJson: type: string description: JSON describing the query parameters appended to the custom link createdAt: type: string format: date-time description: When the screener was created (ISO 8601) updatedAt: type: string format: date-time description: When the screener was last updated (ISO 8601) required: - id - workspaceId - studyId - type - showSchedulerToQualified - qualifyByDefault - createdAt - updatedAt description: A study's screener top-level properties ScreenerQuestionResponse: oneOf: - $ref: '#/components/schemas/SimpleScreenerQuestionResponse' - $ref: '#/components/schemas/OptionScreenerQuestionResponse' - $ref: '#/components/schemas/DropdownScreenerQuestionResponse' - $ref: '#/components/schemas/MatrixScreenerQuestionResponse' discriminator: propertyName: category mapping: simple: $ref: '#/components/schemas/SimpleScreenerQuestionResponse' option: $ref: '#/components/schemas/OptionScreenerQuestionResponse' dropdown: $ref: '#/components/schemas/DropdownScreenerQuestionResponse' matrix: $ref: '#/components/schemas/MatrixScreenerQuestionResponse' description: >- A screener question. Template-sourced questions are returned expanded into their concrete category. PutTemplateScreenerQuestion: type: object properties: category: type: string enum: - template questionTemplateId: type: string description: The id of the workspace question template to instantiate name: type: string description: Overrides the template question prompt description: type: string description: Overrides the template question helper text isRequired: type: boolean description: Overrides whether a response is required required: - category - questionTemplateId additionalProperties: false description: >- A question created from a workspace question template. Only name, description, and isRequired may be overridden. PutSimpleScreenerQuestion: type: object properties: category: type: string enum: - simple type: type: string enum: - SHORT_FORM - LONG_FORM - DATE - NUMBER description: >- Whether the question collects short text, long text, a date, or a number name: type: string description: The question prompt description: type: string description: Optional helper text shown beneath the question prompt isRequired: type: boolean default: true description: Whether a response is required before the screener can be submitted mappedToPropertyId: type: string description: Map the response to a person property required: - category - type - name additionalProperties: false description: A short answer, long answer, date, or number question PutOptionScreenerQuestion: type: object properties: category: type: string enum: - option type: type: string enum: - SINGLE_SELECT - MULTI_SELECT description: >- Whether respondents may select one option (SINGLE_SELECT) or several (MULTI_SELECT) name: type: string description: The question prompt description: type: string description: Optional helper text shown beneath the question prompt isRequired: type: boolean default: true description: Whether a response is required before the screener can be submitted rules: type: array items: $ref: '#/components/schemas/ScreenerQuestionRule' description: Qualification or skip logic evaluated against the selected options mappedToPropertyId: type: string description: Map the response to a person property randomizeOrder: type: boolean default: false description: Randomize the order options are shown to each respondent includeOther: type: boolean default: false description: Add a free-text "Other" option otherDisplayText: type: string description: Cannot be supplied unless includeOther is true includeNoneOfTheAbove: type: boolean default: false description: Add a "None of the above" option options: type: array items: $ref: '#/components/schemas/PutScreenerQuestionOptionValue' minItems: 1 maxItems: 25 description: The selectable options, in display order required: - category - type - name - options additionalProperties: false description: A single-select or multi-select question PutDropdownScreenerQuestion: type: object properties: category: type: string enum: - dropdown type: type: string enum: - DROPDOWN description: A dropdown question type name: type: string description: The question prompt description: type: string description: Optional helper text shown beneath the question prompt isRequired: type: boolean default: true description: Whether a response is required before the screener can be submitted rules: type: array items: $ref: '#/components/schemas/ScreenerQuestionRule' description: Qualification or skip logic evaluated against the selected option mappedToPropertyId: type: string description: Map the response to a person property options: type: array items: $ref: '#/components/schemas/PutScreenerQuestionOptionValue' minItems: 1 maxItems: 25 description: The selectable options, in display order required: - category - type - name - options additionalProperties: false description: A dropdown question (no "Other" or "None of the above") PutMatrixScreenerQuestion: type: object properties: category: type: string enum: - matrix type: type: string enum: - MATRIX description: A matrix question type name: type: string description: The question prompt description: type: string description: Optional helper text shown beneath the question prompt isRequired: type: boolean default: true description: Whether a response is required before the screener can be submitted columns: type: array items: type: string maxLength: 40 minItems: 1 maxItems: 25 description: The shared column labels applied to every row rows: type: array items: $ref: '#/components/schemas/PutMatrixScreenerQuestionRow' minItems: 1 maxItems: 25 description: The matrix rows required: - category - type - name - columns - rows additionalProperties: false description: A matrix question with rows and shared columns ScreenerType: type: string enum: - RALLY - SURVEY_MONKEY - TYPEFORM - QUALTRICS - CUSTOM_LINK description: The type of screener ExternalSurveySetupStatus: type: string enum: - IN_PROGRESS - READY - FAILED description: Setup status of an external survey screener SimpleScreenerQuestionResponse: allOf: - $ref: '#/components/schemas/SimpleScreenerQuestion' - type: object properties: isRequired: type: boolean description: >- Whether a response is required before the screener can be submitted id: type: string description: The question id workspaceId: type: string description: The workspace that owns the question questionTemplateId: type: string description: Present for questions created from a template required: - isRequired - id - workspaceId description: A short answer, long answer, date, or number question OptionScreenerQuestionResponse: allOf: - $ref: '#/components/schemas/OptionScreenerQuestion' - type: object properties: isRequired: type: boolean description: >- Whether a response is required before the screener can be submitted randomizeOrder: type: boolean description: Whether options are shown in a random order per respondent includeOther: type: boolean description: Whether the question has a free-text "Other" option otherDisplayText: type: string description: The display text of the free-text "Other" option includeNoneOfTheAbove: type: boolean description: Whether the question has a "None of the above" option id: type: string description: The question id workspaceId: type: string description: The workspace that owns the question questionTemplateId: type: string description: Present for questions created from a template required: - isRequired - randomizeOrder - includeOther - includeNoneOfTheAbove - id - workspaceId description: A single-select or multi-select question DropdownScreenerQuestionResponse: allOf: - $ref: '#/components/schemas/DropdownScreenerQuestion' - type: object properties: isRequired: type: boolean description: >- Whether a response is required before the screener can be submitted id: type: string description: The question id workspaceId: type: string description: The workspace that owns the question questionTemplateId: type: string description: Present for questions created from a template required: - isRequired - id - workspaceId description: A dropdown question (no "Other" or "None of the above") MatrixScreenerQuestionResponse: allOf: - $ref: '#/components/schemas/MatrixScreenerQuestion' - type: object properties: isRequired: type: boolean description: >- Whether a response is required before the screener can be submitted id: type: string description: The question id workspaceId: type: string description: The workspace that owns the question questionTemplateId: type: string description: Present for questions created from a template required: - isRequired - id - workspaceId description: A matrix question with rows and shared columns ScreenerQuestionRule: type: object properties: operator: $ref: '#/components/schemas/ScreenerRuleOperator' optionValues: type: array items: type: string description: >- The option values the operator compares against. Must reference question options, or "OTHER"/"NONE" when enabled. action: $ref: '#/components/schemas/ScreenerRuleAction' qualificationLogic: $ref: '#/components/schemas/ScreenerQualificationLogic' required: - operator - optionValues additionalProperties: false description: Qualification or skip logic for a select or dropdown question PutScreenerQuestionOptionValue: type: object properties: value: type: string description: The display value of the option mappedToPropertyOptionId: type: string description: >- The property option this option maps to. Omit to leave the option unmapped when the question has a mappedToPropertyId. required: - value additionalProperties: false description: An option for a select or dropdown question PutMatrixScreenerQuestionRow: type: object properties: value: type: string maxLength: 100 description: The row label mappedToPropertyId: type: string description: Map this row's response to a person property columnToPropertyOptionId: type: object additionalProperties: type: string description: >- Maps a column value to a property option id. Columns missing from this map are left unmapped. required: - value additionalProperties: false description: A row of a matrix question SimpleScreenerQuestion: type: object properties: category: type: string enum: - simple type: type: string enum: - SHORT_FORM - LONG_FORM - DATE - NUMBER description: >- Whether the question collects short text, long text, a date, or a number name: type: string description: The question prompt description: type: string description: Optional helper text shown beneath the question prompt isRequired: type: boolean default: true description: Whether a response is required before the screener can be submitted mappedToPropertyId: type: string description: Map the response to a person property required: - category - type - name description: A short answer, long answer, date, or number question OptionScreenerQuestion: type: object properties: category: type: string enum: - option type: type: string enum: - SINGLE_SELECT - MULTI_SELECT description: >- Whether respondents may select one option (SINGLE_SELECT) or several (MULTI_SELECT) name: type: string description: The question prompt description: type: string description: Optional helper text shown beneath the question prompt isRequired: type: boolean default: true description: Whether a response is required before the screener can be submitted options: type: array items: $ref: '#/components/schemas/ScreenerQuestionOptionValue' minItems: 1 maxItems: 25 description: The selectable options, in display order rules: type: array items: $ref: '#/components/schemas/ScreenerQuestionRule' description: Qualification or skip logic evaluated against the selected options mappedToPropertyId: type: string description: Map the response to a person property randomizeOrder: type: boolean default: false description: Randomize the order options are shown to each respondent includeOther: type: boolean default: false description: Add a free-text "Other" option otherDisplayText: type: string description: Cannot be supplied unless includeOther is true includeNoneOfTheAbove: type: boolean default: false description: Add a "None of the above" option required: - category - type - name - options description: A single-select or multi-select question DropdownScreenerQuestion: type: object properties: category: type: string enum: - dropdown type: type: string enum: - DROPDOWN description: A dropdown question type name: type: string description: The question prompt description: type: string description: Optional helper text shown beneath the question prompt isRequired: type: boolean default: true description: Whether a response is required before the screener can be submitted options: type: array items: $ref: '#/components/schemas/ScreenerQuestionOptionValue' minItems: 1 maxItems: 25 description: The selectable options, in display order rules: type: array items: $ref: '#/components/schemas/ScreenerQuestionRule' description: Qualification or skip logic evaluated against the selected option mappedToPropertyId: type: string description: Map the response to a person property required: - category - type - name - options description: A dropdown question (no "Other" or "None of the above") MatrixScreenerQuestion: type: object properties: category: type: string enum: - matrix type: type: string enum: - MATRIX description: A matrix question type name: type: string description: The question prompt description: type: string description: Optional helper text shown beneath the question prompt isRequired: type: boolean default: true description: Whether a response is required before the screener can be submitted rows: type: array items: $ref: '#/components/schemas/MatrixScreenerQuestionRow' minItems: 1 maxItems: 25 description: The matrix rows columns: type: array items: type: string maxLength: 40 minItems: 1 maxItems: 25 description: The shared column labels applied to every row required: - category - type - name - rows - columns description: A matrix question with rows and shared columns ScreenerRuleOperator: type: string enum: - IS_EXACTLY - DOESNT_EQUAL - INCLUDES_ANY_OF - INCLUDES_ALL_OF - NOT_INCLUDES_ANY_OF description: The comparison applied by a screener question rule ScreenerRuleAction: oneOf: - type: object properties: type: type: string enum: - END_SCREENER description: End the screener when the rule matches required: - type additionalProperties: false - type: object properties: type: type: string enum: - JUMP description: Jump to another question when the rule matches index: type: integer description: >- The zero-based index of the question to jump to. Must reference a question after this one; use END_SCREENER to route past the last question. required: - type - index additionalProperties: false description: What happens when a rule matches. Omit to continue to the next question. ScreenerQualificationLogic: type: string enum: - QUALIFY - DISQUALIFY description: Omit for jump or end actions that only route the response ScreenerQuestionOptionValue: type: object properties: value: type: string description: The display value of the option mappedToPropertyOptionId: type: string description: >- The property option this option maps to. Omit to leave the option unmapped when the question has a mappedToPropertyId. required: - value description: An option for a select or dropdown question MatrixScreenerQuestionRow: type: object properties: value: type: string maxLength: 100 description: The row label mappedToPropertyId: type: string description: Map this row's response to a person property columnToPropertyOptionId: type: object additionalProperties: type: string description: >- Maps a column value to a property option id. Columns missing from this map are left unmapped. required: - value description: A row of a matrix question headers: X-RateLimit-Limit: description: The maximum number of requests the client is allowed to make. schema: type: integer format: int32 X-RateLimit-Remaining: description: >- The number of requests remaining for the client in the current time window. schema: type: integer format: int32 X-RateLimit-Reset: description: >- The time at which the current time window ends (in Unix timestamp format). schema: type: integer format: int32 Retry-After: description: The number of seconds until the client should retry the request. schema: type: integer format: int32 securitySchemes: bearerAuth: type: http scheme: bearer ````