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

# Create a new study

> Create a new study in your workspace. This can only be a draft study, certain features not supported and require updating in the UI



## OpenAPI

````yaml https://api.rallyuxr.com/api/openapi post /studies
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: 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:
    post:
      tags:
        - Studies
      summary: Create a new study
      description: >-
        Create a new study in your workspace. This can only be a draft study,
        certain features not supported and require updating in the UI
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStudyInput'
      responses:
        '201':
          description: The created 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:
                type: object
                properties:
                  studyId:
                    type: string
                required:
                  - studyId
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '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'
        '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:
  schemas:
    CreateStudyInput:
      type: object
      properties:
        studyType:
          $ref: '#/components/schemas/StudyType'
        recruitmentStrategy:
          $ref: '#/components/schemas/RecruitmentStrategy'
        recruitmentPanelProvider:
          $ref: '#/components/schemas/RecruitmentPanelProvider'
        idOfStudyToDuplicate:
          type: string
          description: >-
            The ID of the study to duplicate. Cannot be used with
            studyTemplateId. Values within the studyPlan will override any
            values from the duplicated study
        studyTemplateId:
          type: string
          description: >-
            The id of the study template. Cannot be used with
            idOfStudyToDuplicate. Values within the studyPlan will override any
            values from the template study
        owners:
          type: object
          properties:
            userIds:
              type: array
              items:
                type: string
              description: The userIds of any owners on the study
            includeSelf:
              type: boolean
              default: false
              description: Whether to include the current API user as an owner
          required:
            - userIds
        teamId:
          type: string
          description: >-
            The ID of the team to associate the study with. Required in Rally
            For Teams
        populationId:
          type: string
          description: >-
            ID of the population where new study sign ups will go to if the
            study public link is active
        studyPlan:
          $ref: '#/components/schemas/CreateStudyPlanInput'
      required:
        - studyPlan
      description: Create study input
    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
    StudyType:
      type: string
      enum:
        - SURVEY
        - INTERVIEWS
        - UNMODERATED_TEST
        - GROUP_INTERVIEW
      description: The type of study. Required if not using a duplicate/study template
    RecruitmentStrategy:
      type: string
      enum:
        - IN_RALLY
        - EXTERNAL
      description: >-
        The recruitment strategy for the study. Required if not using a
        duplicate/study template
    RecruitmentPanelProvider:
      type: string
      enum:
        - RESPONDENT
        - USER_INTERVIEWS
      description: >-
        Set this to change the default recruitment panel provider when
        recruitment strategy is EXTERNAL. Defaults to User Interviews
    CreateStudyPlanInput:
      type: object
      properties:
        name:
          type: string
          description: The internal name of the study
        externalName:
          type: string
          description: The external name of the study
        description:
          type: string
          description: The internal 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
        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
        researchPlanUrl:
          type: string
          description: The URL of the research plan
        participationLimit:
          type: number
          default: 10
          description: The participation limit of the study
        consentFormId:
          type: string
          description: The ID of the consent form
        incentive:
          $ref: '#/components/schemas/StudyPlanCreateIncentive'
        includeScreener:
          type: boolean
          description: >-
            Whether to include a screener. If type is `SURVEY` the default is
            true, if not then false
        brandingConfigId:
          type: string
          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'
      required:
        - name
      description: Study details
    StudyPlanCreateIncentive:
      type: object
      properties:
        incentiveType:
          $ref: '#/components/schemas/InputIncentiveType'
        incentiveBudgetId:
          type: string
          description: The ID of the incentive budget. Not used for CUSTOM
        amount:
          type: number
          description: >-
            The amount of the incentive. If type is CUSTOM use this for MONETARY
            types instead of default value
        currency:
          $ref: '#/components/schemas/IncentiveCurrencyType'
        customIncentiveId:
          type: string
          description: If type is CUSTOM then the ID of the custom incentive
        defaultCustomIncentiveValue:
          type: string
          description: If type is CUSTOM then the default value of the custom incentive
      required:
        - incentiveType
      description: Object required to add an incentive to a 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
    InputIncentiveType:
      type: string
      enum:
        - MONEY_OR_GIFT_CARD
        - CUSTOM
        - CHARITY
      description: Incentive types that can be created by the API
    IncentiveCurrencyType:
      type: string
      enum:
        - USD
        - EUR
        - GBP
        - CAD
        - AUD
        - NZD
      description: The currency of the incentive. Defaults to USD when not provided
  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

````