---
title: "Transition a single flag to a new status"
method: PUT
path: "/flags/{id}/update-status/{status}"
tags: ["Flag"]
---

# Transition a single flag to a new status

`PUT /flags/{id}/update-status/{status}`

Transitions the specified flag to the given target status. Use this endpoint to move one flag through its lifecycle (e.g. acknowledging it, starting outreach, closing it); to move multiple flags in one call, use `PUT /flags/update-status-bulk/{status}` instead. The caller must hold the per-transition permission for the specific source-to-target status pair (see the flag status-transition rules); closed flags are terminal and cannot be transitioned further. The `status` path parameter accepts any of the canonical wire values (`open`, `seen`, `outreachInProgress`, `sentToCommittee`, `closed`, `needsVerification`) or the aliases `markAsSeen`/`mark_as_seen`, `needs_verification`, `outreach_in_progress`, and `sent_to_committee` — matching is case-insensitive, so any casing of any of these values is accepted. The request body is optional: supply a free-text `comment` and/or one or more `files` to attach context to the transition, or omit the body entirely. Returns the full updated flag record on success. A FlagHistory record is always created, and if files were supplied they are stored to GCS and linked as FlagHistoryAttachment records — both are best-effort and do not fail the call if they error. Not idempotent: since no status has a transition to itself, repeating the same call a second time (the flag now already at the target status) returns 409.

## Path parameters

- `id` string, required
- `status` string, required

## Headers

- `tenant-id` string, required

## Response `200`

The updated flag record, reflecting the new status. The internal `tenantProviderId` and `hash` columns are omitted — everything else in the referenced schema is returned verbatim.

- FlagResponse
  - `id` string
  - `tenantProviderId` string
  - `flagTypeId` string
  - `data` JsonNode
    - `empty` boolean
    - `valueNode` boolean
    - `containerNode` boolean
    - `missingNode` boolean
    - `array` boolean
    - `object` boolean
    - `nodeType` 'ARRAY' | 'BINARY' | 'BOOLEAN' | 'MISSING' | 'NULL' | 'NUMBER' | 'OBJECT' | 'POJO' | 'STRING'
    - `pojo` boolean
    - `number` boolean
    - `integralNumber` boolean
    - `floatingPointNumber` boolean
    - `short` boolean
    - `int` boolean
    - `long` boolean
    - `float` boolean
    - `double` boolean
    - `bigDecimal` boolean
    - `bigInteger` boolean
    - `textual` boolean
    - `boolean` boolean
    - `null` boolean
    - `binary` boolean
  - `createdAt` string, date
  - `createdBy` string
  - `updatedAt` string, date
  - `updatedBy` string
  - `originMonitoringWorkflowId` string
  - `hash` string
  - `tenantId` string
  - `practitionerPrefix` string
  - `practitionerFirstName` string
  - `practitionerMiddleName` string
  - `practitionerLastName` string
  - `practitionerNpi` string
  - `statesToCredential` string[]
  - `practitionerType` string[]
  - `credentialingStatus` string
  - `dataSource` string
  - `practitionerDateOfBirth` string
  - `practitionerEmail` string
  - `lastCredentialedDate` string
  - `markedSeenAt` string, date
  - `markedSeenBy` string

## Other responses

- `400` — Bad Request - the status path parameter does not match any known status or alias, or the tenant-id header is missing
- `401` — Unauthorized - authentication is required; the JWT is missing or invalid
- `403` — Forbidden - the caller lacks the permission required for this specific source-to-target transition; this is distinct from the flag being unreachable from its current status, which returns 409
- `404` — Not Found - no flag exists with the given id for the requesting tenant
- `409` — Conflict - the transition is not allowed: either the flag is already closed (a terminal state with no outgoing transitions), or there is no defined path from the flag's current status to the requested target status. This includes supplying the flag's current status as the target, since no status has a transition to itself.
- `500` — Internal server error - an unexpected error occurred while processing the request

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)