> ## Documentation Index > Fetch the complete documentation index at: https://docs.modernloop.io/llms.txt > Use this file to discover all available pages before exploring further. # Update a job stage > Updates a job stage's settings. Targets the stage settings only; the base stage (name, index, ATS identity, schedulable) is ATS-sync-owned and read-only. Every supplied settings group merges per field, including `self_schedule_defaults` and `availability_request_defaults`; omitted fields are preserved. At least one group is required. Set `automation.create_automated_task_on_behalf_of` to `null` to clear it. The Java handler does not support clearing `automation.default_task`; omit it to preserve the current value. Requires a WRITE-scoped token with the beta:jobs:write entitlement. **Beta**: this endpoint may change or be removed without notice while in beta. There is no compatibility promise until it reaches general availability. ## OpenAPI ````yaml /openapi.json patch /v1/job-stages/{jobStageId} openapi: 3.1.0 info: title: ModernLoop Platform API version: 0.1.0 description: The ModernLoop Platform API for managing recruiting workflows. contact: email: support@modernloop.io servers: - url: https://api.modernloop.io security: [] tags: - name: Application - name: Candidate - name: Interview Event - name: Interview Module - name: Interviewer - name: Job - name: Job Stage - name: Organization - name: Schedule - name: Scheduling Task - name: Task Queue - name: Template paths: /v1/job-stages/{jobStageId}: patch: tags: - Job Stage summary: Update a job stage description: >- Updates a job stage's settings. Targets the stage settings only; the base stage (name, index, ATS identity, schedulable) is ATS-sync-owned and read-only. Every supplied settings group merges per field, including `self_schedule_defaults` and `availability_request_defaults`; omitted fields are preserved. At least one group is required. Set `automation.create_automated_task_on_behalf_of` to `null` to clear it. The Java handler does not support clearing `automation.default_task`; omit it to preserve the current value. Requires a WRITE-scoped token with the beta:jobs:write entitlement. operationId: updateJobStage parameters: - schema: type: string pattern: >- ^(?:stg_)?(?:[0-9a-fA-F]{32}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ description: >- a job stage ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive. example: stg_a1b2c3d4e5f64789a1b2c3d4e5f64789 required: true name: jobStageId in: path requestBody: content: application/json: schema: $ref: '#/components/schemas/JobStagePatch' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/JobStage' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '410': description: Gone content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: JobStagePatch: type: object properties: settings: $ref: '#/components/schemas/JobStageSettingsPatch' required: - settings additionalProperties: false JobStage: type: object properties: id: type: string pattern: ^stg_[0-9a-f]{32}$ description: >- Canonical job stage ID (stg_ followed by 32 lowercase hexadecimal UUID characters). example: stg_a1b2c3d4e5f64789a1b2c3d4e5f64789 job_id: type: string pattern: ^job_[0-9a-f]{32}$ description: >- Canonical job ID (job_ followed by 32 lowercase hexadecimal UUID characters). example: job_a1b2c3d4e5f64789a1b2c3d4e5f64789 name: type: string index: type: integer schedulable: type: boolean ats: type: - object - 'null' properties: type: type: string enum: - GREENHOUSE - ASHBY - LEVER - WORKDAY - SMARTRECRUITERS - GEM - KOMBO id: type: string required: - type - id has_custom_interview_plan: type: boolean settings: type: object properties: automation: type: object properties: is_automated_task_enabled: type: boolean create_automated_task_on_behalf_of: type: - string - 'null' pattern: ^emp_[0-9a-f]{32}$ description: >- Canonical employee ID (emp_ followed by 32 lowercase hexadecimal UUID characters). example: emp_a1b2c3d4e5f64789a1b2c3d4e5f64789 default_task: type: - string - 'null' enum: - ASSIGN_TASK - AVAILABILITY_REQUEST - SELF_SCHEDULE_REQUEST description: >- Default action created when this stage automation runs. ASSIGN_TASK is the stage-default action name used by the job-stage service, distinct from a task-create request's ASSIGN command type. required: - is_automated_task_enabled - create_automated_task_on_behalf_of - default_task candidate_notifications: type: object properties: should_send_email: type: boolean should_send_calendar_invite: type: boolean should_send_chat_message: type: boolean should_send_candidate_pulse: type: boolean required: - should_send_email - should_send_calendar_invite - should_send_chat_message - should_send_candidate_pulse self_schedule_defaults: type: - object - 'null' properties: advance_notice_in_hours: type: - integer - 'null' rolling_days: type: - integer - 'null' use_rolling_days: type: - boolean - 'null' number_of_days: type: - integer - 'null' location: type: - string - 'null' enum: - NONE - ZOOM - GOOGLE_MEET - PHONE - CUSTOM - MICROSOFT_TEAMS description: >- Location type for self-scheduled interviews. GOOGLE_MEET creates a Google Meet link. custom_location: type: - string - 'null' is_private_calendar_event: type: - boolean - 'null' should_respect_load_limit: type: - boolean - 'null' can_schedule_over_recruiting_keywords: type: - boolean - 'null' can_schedule_over_available_keywords: type: - boolean - 'null' can_schedule_over_free_time: type: - boolean - 'null' candidate_note: type: - string - 'null' required: - advance_notice_in_hours - rolling_days - use_rolling_days - number_of_days - location - custom_location - is_private_calendar_event - should_respect_load_limit - can_schedule_over_recruiting_keywords - can_schedule_over_available_keywords - can_schedule_over_free_time - candidate_note availability_request_defaults: type: - object - 'null' properties: number_of_days: type: - integer - 'null' minutes_per_day: type: - integer - 'null' minimum_time_block_minutes: type: - integer - 'null' advance_notice_minutes: type: - integer - 'null' rolling_days: type: - integer - 'null' use_rolling_days: type: - boolean - 'null' timeframe_number_of_days: type: - integer - 'null' should_respect_load_limit: type: - boolean - 'null' can_schedule_over_recruiting_keywords: type: - boolean - 'null' can_schedule_over_available_keywords: type: - boolean - 'null' can_schedule_over_free_time: type: - boolean - 'null' candidate_note: type: - string - 'null' required: - number_of_days - minutes_per_day - minimum_time_block_minutes - advance_notice_minutes - rolling_days - use_rolling_days - timeframe_number_of_days - should_respect_load_limit - can_schedule_over_recruiting_keywords - can_schedule_over_available_keywords - can_schedule_over_free_time - candidate_note required: - automation - candidate_notifications - self_schedule_defaults - availability_request_defaults created_at: type: string format: date-time description: ISO 8601 timestamp. updated_at: type: string format: date-time description: ISO 8601 timestamp. required: - id - job_id - name - index - schedulable - ats - has_custom_interview_plan - settings - created_at - updated_at ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHENTICATED - API_ACCESS_DISABLED - SCOPE_MISSING - INSUFFICIENT_SCOPE - VALIDATION_FAILED - INVALID_CURSOR - PAYLOAD_TOO_LARGE - NOT_FOUND - NOT_FOUND_MAY_BE_SYNCING - CANDIDATE_ANONYMIZED - TASK_STAGE_NOT_SCHEDULABLE - DUPLICATE_REQUEST_OPEN - IDEMPOTENCY_KEY_REQUIRED - IDEMPOTENCY_KEY_REUSED - PREVIEW_EXPIRED - PREVIEW_STALE - RATE_LIMITED - CONFLICT - NOT_IMPLEMENTED - INTERNAL - UPSTREAM_TIMEOUT message: type: string docs_url: type: string format: uri required: - code - message required: - error JobStageSettingsPatch: type: object properties: automation: type: object properties: is_automated_task_enabled: type: boolean create_automated_task_on_behalf_of: type: - string - 'null' pattern: >- ^(?:emp_)?(?:[0-9a-fA-F]{32}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ description: >- an employee ID. Accepts the canonical prefixed compact UUID, a prefixed dashed UUID, a bare dashed UUID, or a bare compact UUID; input is case-insensitive. example: emp_a1b2c3d4e5f64789a1b2c3d4e5f64789 default_task: type: string enum: - ASSIGN_TASK - AVAILABILITY_REQUEST - SELF_SCHEDULE_REQUEST description: >- Sets the default task when supplied; omission preserves it. Null is not accepted because the Java handler treats the unspecified enum as unchanged rather than clear. description: >- Partially updates automation settings; omitted fields preserve their current values. candidate_notifications: type: object properties: should_send_email: type: boolean should_send_calendar_invite: type: boolean should_send_chat_message: type: boolean should_send_candidate_pulse: type: boolean description: >- Partially updates candidate-notification settings; omitted fields preserve their current values. self_schedule_defaults: type: object properties: advance_notice_in_hours: type: - integer - 'null' rolling_days: type: - integer - 'null' use_rolling_days: type: - boolean - 'null' number_of_days: type: - integer - 'null' location: type: - string - 'null' enum: - NONE - ZOOM - GOOGLE_MEET - PHONE - CUSTOM - MICROSOFT_TEAMS description: >- Location type for self-scheduled interviews. GOOGLE_MEET creates a Google Meet link. custom_location: type: - string - 'null' is_private_calendar_event: type: - boolean - 'null' should_respect_load_limit: type: - boolean - 'null' can_schedule_over_recruiting_keywords: type: - boolean - 'null' can_schedule_over_available_keywords: type: - boolean - 'null' can_schedule_over_free_time: type: - boolean - 'null' candidate_note: type: - string - 'null' description: >- Partially updates self-schedule defaults; omitted fields preserve their current values. availability_request_defaults: type: object properties: number_of_days: type: - integer - 'null' minutes_per_day: type: - integer - 'null' minimum_time_block_minutes: type: - integer - 'null' advance_notice_minutes: type: - integer - 'null' rolling_days: type: - integer - 'null' use_rolling_days: type: - boolean - 'null' timeframe_number_of_days: type: - integer - 'null' should_respect_load_limit: type: - boolean - 'null' can_schedule_over_recruiting_keywords: type: - boolean - 'null' can_schedule_over_available_keywords: type: - boolean - 'null' can_schedule_over_free_time: type: - boolean - 'null' candidate_note: type: - string - 'null' description: >- Partially updates availability-request defaults; omitted fields preserve their current values. description: Job-stage settings patch. Include at least one settings group. securitySchemes: bearerAuth: type: http scheme: bearer description: API tokens are passed as Bearer tokens. ````