> ## 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.

# Publish a draft study

> Publish a draft study and all of its associated data (screener, questions, options), applying its pending draft changes and moving it out of DRAFT status so it goes live. This is the same publish action available in the Rally app.



## OpenAPI

````yaml https://api.rallyuxr.com/api/openapi post /studies/{studyId}/publish
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}/publish:
    post:
      tags:
        - Studies
      summary: Publish a draft study
      description: >-
        Publish a draft study and all of its associated data (screener,
        questions, options), applying its pending draft changes and moving it
        out of DRAFT status so it goes live. This is the same publish action
        available in the Rally app.
      parameters:
        - $ref: '#/components/parameters/StudyId'
      responses:
        '200':
          description: The published study
          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/StudyWithScreener'
        '400':
          description: Bad Request
          content:
            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
  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
  schemas:
    StudyWithScreener:
      allOf:
        - $ref: '#/components/schemas/Study'
        - type: object
          properties:
            screener:
              anyOf:
                - $ref: '#/components/schemas/ScreenerResponse'
                - type: 'null'
              description: >-
                The study's screener with all of its questions. Null when the
                study has no screener or the caller cannot read screeners. Not
                included in list responses.
          required:
            - screener
      description: Study object including its screener
    StudyId:
      type: string
    Study:
      type: object
      properties:
        studyId:
          type: string
        studyType:
          $ref: '#/components/schemas/StudyType'
        recruitmentStrategy:
          allOf:
            - $ref: '#/components/schemas/RecruitmentStrategy'
            - description: The recruitment strategy for the study
        status:
          $ref: '#/components/schemas/StudyStatus'
        studyPlan:
          $ref: '#/components/schemas/StudyPlan'
        createdAt:
          type: string
          format: date-time
        createdFromTemplateId:
          type:
            - string
            - 'null'
          description: >-
            The ID of the template this study was created from, or null if not
            created from a template
        owners:
          type: array
          items:
            $ref: '#/components/schemas/StudyOwner'
      required:
        - studyId
        - studyType
        - recruitmentStrategy
        - status
        - studyPlan
        - createdAt
        - createdFromTemplateId
        - owners
      description: Study object
    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
    StudyType:
      type: string
      enum:
        - SURVEY
        - INTERVIEWS
        - UNMODERATED_TEST
        - GROUP_INTERVIEW
      description: The type of study
    RecruitmentStrategy:
      type: string
      enum:
        - IN_RALLY
        - EXTERNAL
      description: >-
        The recruitment strategy for the study. Required if not using a
        duplicate/study template
    StudyStatus:
      type: string
      enum:
        - DRAFT
        - ACTIVE
        - PAUSED
        - CLOSED
      description: The status of the study
    StudyPlan:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          description: The internal name of the study
        externalName:
          type:
            - string
            - 'null'
          description: The external name of the study
        description:
          type:
            - string
            - 'null'
          description: The internal description of the study
        externalDescription:
          type:
            - string
            - 'null'
          description: The external description of the study
        startDate:
          anyOf:
            - type: string
              format: date
              description: The start date of the study in YYYY-MM-DD format
              example: '2025-01-01'
            - type: string
              format: date-time
              description: >-
                The start date of the study in ISO 8601 in UTC(with no offset).
                The time is truncated
              example: '2025-01-01T00:00:00Z'
              deprecated: true
            - type: 'null'
        endDate:
          anyOf:
            - type: string
              format: date
              description: The end date of the study in YYYY-MM-DD format
              example: '2025-01-02'
            - type: string
              format: date-time
              description: >-
                The end date of the study in ISO 8601 in UTC(with no offset).
                The time is truncated
              example: '2025-01-02T00:00:00Z'
              deprecated: true
            - type: 'null'
        researchPlanUrl:
          type:
            - string
            - 'null'
          description: The URL of the research plan
        participationLimit:
          type:
            - number
            - 'null'
          default: 10
          description: The participation limit of the study
        consentFormId:
          type:
            - string
            - 'null'
          description: The ID of the consent form
        incentive:
          $ref: '#/components/schemas/StudyPlanIncentive'
        includeScreener:
          type: boolean
          description: >-
            Whether to include a screener. If type is `SURVEY` the default is
            true, if not then false
        brandingConfigId:
          type:
            - string
            - 'null'
          description: >-
            The ID of the branding configuration. Setting it mirrors changing
            the branding in-app: it also updates the study landing page's button
            color and, when the branding config has a workspace email, the
            study's booking-confirmation, booking-cancellation,
            interview-reminder, and interview-reschedule email defaults. On
            update, pass null to clear the study's branding.
        language:
          $ref: '#/components/schemas/LanguageCode'
        scheduler:
          $ref: '#/components/schemas/StudyPlanScheduler'
      required:
        - name
        - externalName
        - description
        - externalDescription
        - startDate
        - endDate
        - researchPlanUrl
        - participationLimit
        - consentFormId
        - incentive
        - includeScreener
        - brandingConfigId
        - language
      description: Study plan object
    StudyOwner:
      type: object
      properties:
        userId:
          type: string
        emailAccountId:
          type: string
        fullname:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
      required:
        - userId
        - emailAccountId
        - fullname
        - email
      description: Study owner object
    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.
    StudyPlanIncentive:
      type:
        - object
        - 'null'
      properties:
        incentiveType:
          $ref: '#/components/schemas/IncentiveType'
        incentiveBudgetId:
          type:
            - string
            - 'null'
          description: The ID of the incentive budget
        amount:
          type:
            - number
            - 'null'
          description: The amount of the incentive
        currency:
          allOf:
            - $ref: '#/components/schemas/IncentiveCurrencyType'
            - description: The currency of the incentive
        customIncentiveId:
          type:
            - string
            - 'null'
          description: If type is CUSTOM then the ID of the custom incentive
        defaultCustomIncentiveValue:
          type:
            - string
            - 'null'
          description: If type is CUSTOM then the default value of the custom incentive
      required:
        - incentiveType
        - incentiveBudgetId
        - amount
        - customIncentiveId
        - defaultCustomIncentiveValue
      description: The incentive details for the study
    LanguageCode:
      type: string
      enum:
        - en
        - es
        - fr
        - it
        - ro
        - pt
        - pl
        - de
        - nl
        - ja
        - pt_BR
        - ko
        - cs
        - hi
        - sk
        - ar
        - tr
      default: en
      description: The language code for the study
    StudyPlanScheduler:
      type:
        - object
        - 'null'
      properties:
        interviewDurationMinutes:
          type: integer
          description: The planned interview duration in minutes.
          example: 60
      required:
        - interviewDurationMinutes
      description: >-
        Scheduler configuration for the study. Read-only. Populated only when
        `studyType` is `INTERVIEWS` and the study has a configured scheduler;
        otherwise the parent `scheduler` field is null (i.e. for `SURVEY`,
        `UNMODERATED_TEST`, `GROUP_INTERVIEW`, or `INTERVIEWS` studies without a
        scheduler row).
    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
    IncentiveType:
      type: string
      enum:
        - MONEY_OR_GIFT_CARD
        - MONEY_OR_GIFT_CARD_WITH_TREMENDOUS
        - EXTERNAL_MONEY_OR_GIFT_CARD
        - CHARITY
        - CUSTOM
        - RESPONDENT_MONEY
        - RECRUITMENT_FEE
      description: The type of incentive
    IncentiveCurrencyType:
      type: string
      enum:
        - USD
        - EUR
        - GBP
        - CAD
        - AUD
        - NZD
      description: The currency of the incentive. Defaults to USD when not provided
    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
    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
    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
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````