---
updatedAt: 2026-06-16T20:13:34.000Z
agentTools:
  projectIndex: https://developer.breezy.hr/llms.txt
---

# /company/{id}/position/{id}/candidate/{id}/stage

Moves the candidate to a different stage in the position's pipeline, identified by `stage_id`.

`stage_id` must match a stage in that position's pipeline (falling back to the company's default pipeline); an unknown stage id fails the request. Every successful move records a stage-change activity and fires the corresponding webhook. Moving into a stage with configured actions (e.g., HRIS/onboarding integrations) also triggers those integrations, and moving into a "Hired"-type stage marks the candidate hired. Returns no content (204) on success.

# OpenAPI definition

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Breezy HR Public API",
    "version": "3",
    "description": "The Breezy HR public API (v3) provides programmatic access to your recruiting data.\nAll endpoints are relative to `https://api.breezy.hr/v3`.\n\n## Authentication\n\nPass a **Personal Access Token (PAT)** in the `Authorization` header:\n```\nAuthorization: Bearer breezy_pat_<token>\n```\n\nAlternatively, call `POST /v3/signin` with email and password to receive a session\n`access_token`, then pass it the same way.\n\nBoth header forms are accepted for PATs and session tokens: `Authorization: Bearer <token>`\nand the bare `Authorization: <token>`. The `Bearer` scheme is matched case-insensitively.\n\n## IDs\n\nAll resource IDs are 12–14 character lowercase hex strings (e.g. `a3f9c1d2e4b5`).\nEU-region resources use 14-character IDs ending in `01`.\n\n## Dates\n\nAll date/timestamp fields are ISO 8601 strings.\n\n## Errors\n\nAll error responses use the shape:\n```json\n{ \"error\": { \"type\": \"string\", \"message\": \"string\" } }\n```\n\nEvery `/company/{companyId}/...` endpoint returns `403` with type `companyMembershipRequired`\nwhen the authenticated user is not a member of that company, for example after the user who\ncreated the token was removed from the account.\n"
  },
  "servers": [
    {
      "url": "https://api.breezy.hr/v3",
      "description": "Production"
    }
  ],
  "security": [
    {
      "TokenAuth": []
    }
  ],
  "tags": [
    {
      "name": "Candidates",
      "description": "Candidate management and all sub-resources"
    }
  ],
  "components": {
    "securitySchemes": {
      "TokenAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Personal Access Token (PAT) or session token from POST /v3/signin, passed in the Authorization header either bare or with a Bearer prefix (both forms are accepted). Declared as apiKey rather than http/bearer so that tools do not force the prefix - the bare form is equally valid."
      }
    }
  },
  "paths": {
    "/company/{companyId}/position/{positionId}/candidate/{candidateId}/stage": {
      "put": {
        "operationId": "setCandidateStage",
        "summary": "/company/{id}/position/{id}/candidate/{id}/stage",
        "tags": [
          "Candidates"
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "positionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "candidateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "description": "Moves the candidate to a different stage in the position's pipeline, identified by `stage_id`.\n\n`stage_id` must match a stage in that position's pipeline (falling back to the company's default pipeline); an unknown stage id fails the request. Every successful move records a stage-change activity and fires the corresponding webhook. Moving into a stage with configured actions (e.g., HRIS/onboarding integrations) also triggers those integrations, and moving into a \"Hired\"-type stage marks the candidate hired. Returns no content (204) on success.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "stage_id"
                ],
                "properties": {
                  "stage_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Stage updated"
          }
        }
      }
    }
  }
}
````