> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Update candidate stage > Moves a candidate to a different pipeline stage within a job. **Flexible identification**: Accepts job identification by `job_id` or `job_name`, candidate identification by `candidate_id`, `candidate_email`, or `candidate_name`, and stage identification by `stage_id` or `stage_name`. **Job resolution**: The endpoint resolves the job in this order: `job_id`, the job associated with `candidate_id`, `job_name`, then the person's most recent active candidacy created within the previous 180 days. When `candidate_id` is provided, its associated job takes precedence over `job_name`. **Discovering stage IDs/names**: Use `GET /v1/jobs/{id}` to see the full `pipeline_stages` array with stage IDs, names, and ordering for a specific job. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/candidates/update-stage openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/candidates/update-stage: post: tags: - Candidates summary: Update candidate stage description: >- Moves a candidate to a different pipeline stage within a job. **Flexible identification**: Accepts job identification by `job_id` or `job_name`, candidate identification by `candidate_id`, `candidate_email`, or `candidate_name`, and stage identification by `stage_id` or `stage_name`. **Job resolution**: The endpoint resolves the job in this order: `job_id`, the job associated with `candidate_id`, `job_name`, then the person's most recent active candidacy created within the previous 180 days. When `candidate_id` is provided, its associated job takes precedence over `job_name`. **Discovering stage IDs/names**: Use `GET /v1/jobs/{id}` to see the full `pipeline_stages` array with stage IDs, names, and ordering for a specific job. operationId: updateCandidateStage requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateCandidateStageBody' responses: '200': description: Stage updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateCandidateStageResponse' example: success: true data: candidate_id: 123e4567-e89b-12d3-a456-426614174000 person_id: 234e5678-e90a-12b3-c456-789012345678 job_id: 234e5678-e90a-12b3-c456-789012345678 previous_stage_id: 345e6789-e01b-23c4-d567-890123456789 new_stage_id: 456e7890-e12b-34d5-a678-901234567890 '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: UpdateCandidateStageBody: type: object properties: job_id: type: string format: uuid description: >- Job UUID. Highest-precedence job identifier. Get IDs from POST /v1/jobs/search. job_name: type: string minLength: 1 description: >- Job title to match. Used only when job_id and candidate_id do not resolve a job. If no job is resolved, the endpoint falls back to the person’s most recent active candidacy created within the previous 180 days. candidate_id: type: string format: uuid description: >- Candidate UUID. Its associated job is used after an explicit job_id and before job_name. Provide candidate_id, candidate_email, or candidate_name. candidate_email: type: string format: email description: Candidate email to look up. Used when candidate_id is not provided. candidate_name: type: string minLength: 1 description: >- Candidate full name to look up. Fallback when email and ID are not provided. stage_id: type: string minLength: 1 description: >- Target pipeline stage UUID. Provide either stage_id or stage_name. Get IDs from GET /v1/jobs/{id} → pipeline_stages. stage_name: type: string minLength: 1 description: >- Target pipeline stage name (e.g. "Technical Interview"). Used when stage_id is not provided. UpdateCandidateStageResponse: type: object properties: success: type: boolean description: Whether the stage update succeeded. data: type: object properties: candidate_id: type: string description: Candidate UUID that was updated. job_id: type: string description: Job UUID. person_id: type: string description: Associated person UUID. previous_stage_id: type: - string - 'null' description: Pipeline stage UUID the candidate was in before the move. new_stage_id: type: string description: Pipeline stage UUID the candidate was moved to. required: - success - data securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````