---
title: "Transition application status"
method: POST
path: "/v1/applications/{application_id}/actions/transition_status"
tags: ["Applications"]
---

# Transition application status

`POST /v1/applications/{application_id}/actions/transition_status`

## Request

- Base URL: `https://api.yardstick.team`
- URL: `https://api.yardstick.team/v1/applications/{application_id}/actions/transition_status`
- Auth: HTTP bearer

Transition application status

**Required scopes:** `applications:write`, `applications:transition_status`

Non-terminal transitions may write immediately. Sensitive terminal or provider-dependent transitions return approval-required or blocked envelopes; this route does not send communications, create scheduling links, update scorecards, publish jobs, archive records, or create reports. Target the move by `status` (resolved to the configured stage internally) or, additively, by `pipeline_stage_id` (move to a configured stage by id; `status` if also sent must equal the stage's mapped status). The same denied-state semantics apply either way: an unmet per-stage action gate returns HTTP 409 `action_gate_blocked`, and an approval-required target returns the HTTP 202 approval-preview envelope. A mutating response reports the resolved `pipeline_stage_id`.

**Example (curl):**

```bash
curl -X POST https://api.yardstick.team/v1/applications/app_def456/actions/transition_status \
  -H 'Authorization: Bearer ys_sk_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7c3a…' \
  -d '{"status":"Screening","reason":"Meets baseline requirements"}'
```

**Example (TypeScript):**

```ts
await fetch(
  "https://api.yardstick.team/v1/applications/app_def456/actions/transition_status",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.YS_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      status: "Screening",
      reason: "Meets baseline requirements",
    }),
  },
);
```

## Path parameters

- `application_id` string, required

## Headers

- `Idempotency-Key` string, required
- `X-Request-Id` string

## Request body

- object
  - `status` string
  - `reason` string
  - `employment_start_date` string
  - `binding` object
    - `preview_hash` string, required
    - `approved_action_key` string, required
    - `approved_input_hash` string, required
    - `approved_idempotency_key` string, required
    - `resource_version_precondition` string, required
  - `pipeline_stage_id` string

## Response `200`

Success

- union: Application status-transition action response. Direct non-terminal transitions may mutate; sensitive or unverified transitions return approval-required or blocked envelopes.
  - object: Application response returned for idempotent or direct status transitions.
    - `is_candidate` boolean, required: Explicitly admitted to the interview process; Review Applications and Candidates are mutually exclusive per application.
    - `candidate_admission_id` string, uuid, nullable, required: Raw current admission UUID, required as expected_admission_id when undoing.
    - `candidate_admitted_at` string, nullable, required
    - `candidate_admission_origin` string, nullable, required
    - `candidate_activity_started_at` string, nullable, required: Non-null after durable candidate activity; undo is then unavailable.
    - `id` string, required: Display id, e.g. `app_<base32>`
    - `object` 'application', required
    - `person_id` string, required: Canonical `per_...` person id.
    - `status` string, required
    - `stage` string, required: Deprecated free-form stage label. Status transitions never change it; read `pipeline_stage_id` for the pipeline position.
    - `pipeline_stage_id` string, nullable, required: Display id (`pst_<base32>`) of the configured pipeline stage (board column) the application sits in; every status transition moves it to the stage mapped to the new status. Null when no configured stage is assigned.
    - `job_id` string, nullable, required: Canonical `job_...` Job id when the application is linked to a Job; null for legacy or unlinked applications.
    - `job_posting_id` string, nullable, required
    - `source` object, required
      - `token_id` string, nullable, required
      - `label` string, nullable, required
    - `livemode` boolean, required
    - `created` string, nullable, required
    - `updated` string, nullable, required
    - `archived_at` string, nullable, required: ISO-8601 UTC; non-null when the application has been archived.
    - `archived_reason` string, nullable, required: Free-text archive reason captured at archive time; nullable.
    - `transition` object, required
      - `idempotent` boolean, required
      - `mutated` boolean, required
      - `execution_mode` 'direct_write'
      - `pipeline_stage_id` string: Display id (`pst_<base32>`) of the configured pipeline stage the move resolved to and wrote. Present on a mutating transition (direct write or approval bind). The status is derived from this stage's mapped status, so a request may target the move either by `status` or by `pipeline_stage_id`.
  - object: Application status-transition action envelope returned when a transition requires approval, is blocked by an unmet action gate (`action_gate_blocked`), or is blocked pending verification.
    - `object` 'application_status_transition', required
    - `action` 'application.transition_status', required
    - `application_id` string
    - `resource` object
      - `type` 'application', required
      - `id` string, required
    - `execution_mode` 'direct_write' | 'approval_required' | 'blocked_until_verified', required
    - `approval_required` boolean
    - `blocked` boolean
    - `action_gate_blocked` boolean: Present and `true` when an unmet per-stage action gate blocked the move. A distinct discriminator from approval/validity blocks: it is returned (HTTP 409) BEFORE any approval preview, so a gated move never reaches the approval ceremony while the gate is unmet. Pair with `gate` for the machine-readable reason.
    - `mutated` boolean, required
    - `current_status` string, required
    - `proposed_status` string, required
    - `proposed_pipeline_stage_id` string: The pipeline stage (`pst_` id, the board column) the application will move to when the approved transition is bound. Display-only on the approval preview; the legacy `stage` label does not move.
    - `reason` string, nullable
    - `gate` object: Detail of the unmet action gate, present only alongside `action_gate_blocked: true`.
      - `type` string, required: The unmet gate type, e.g. `scorecard_submitted`.
      - `reason` string, required: Human-readable, agent-actionable explanation, e.g. `Needs a submitted scorecard for the current round`.
    - `approval` object
      - `gate` string, required
      - `reason` string, required
      - `preview_required` string[], required
      - `binding` object, required
        - `required_fields` string[], required
        - `approved_action_key` 'application.transition_status', required
        - `resource_version_precondition` string, nullable, required
    - `required_scopes` string[]

## Other responses

- `400`: Invalid request
- `401`: Authentication failure
- `403`: Permission denied (scope or feature flag)
- `404`: Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.
- `409`: Conflict (e.g. idempotency key reuse with different body)
- `429`: Rate limited
- `500`: Internal error

---

[API](https://skmtc.dev/yardstick/apis/yardstick-public-api.md) · [All operations](https://skmtc.dev/yardstick/apis/yardstick-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yardstick/apis/yardstick-public-api/revisions/35b5a6e88b35?raw)