Skip to main content

Flag

APIs for managing flag entities

📄️Transition multiple flags to a new status in one call

Transitions a list of flags to the given target status in a single request, evaluating each flag independently against its own current status and the caller's permissions. Use this instead of calling PUT /flags/{id}/update-status/{status} once per flag; per-flag failures do not abort the batch. Two selection modes are supported: the default 'ids' mode, where the JSON body or multipart form supplies flagIds directly, plus optional comment and/or files applied to every successfully transitioned flag; and a JSON-only 'filter' mode (set type to 'filter'), where filter selects all matching flags server-side and expectedCount is the client's snapshot count used to detect drift — the request is rejected with 409 if the live count no longer matches. Filter-based selection can be disabled by configuration, in which case it returns 503. The status path parameter accepts the same canonical wire values and aliases as PUT /flags/{id}/update-status/{status} (case-insensitive). The caller must hold at least one of the listed per-transition permissions to pass the outer authorization gate; each flag is then re-checked individually against the specific transition it requires. Always returns HTTP 200, even when every flag in the batch fails — inspect the response body's successful/failed arrays and successCount/failureCount for the actual outcome. An empty or omitted flagIds list returns 200 with totalCount, successCount, and failureCount all zero.

📄️Add a New License Found flag's state(s) to the practitioner's states to credential

For a new_credential_found flag on state-licenses, DEA or CDS: appends the flag's single state (always taken from the flag's metaData.state; the request's states must be absent/empty) to statesToCredential. For a compact-license flag (no single state; coverage is metaData.coveredStates, a list): the request's states is required, and must be a non-empty subset of the flag's own coveredStates — a state already on the practitioner is accepted and treated as a no-op, so a retry after a partial success is never rejected — every requested state is added. Either way, states are written to statesToCredential on the practitioner's tenant record (or roster record when only that one carries the list), the flag is marked seen with the note (for an outreachInProgress flag the status is left and the note is recorded on its history), then the state(s) are added to the active monitoring workflow and its flags are recalculated, which closes the flag. Allowed on open, needsVerification, sentToCommittee and outreachInProgress flags. For state-licenses/DEA/CDS, a seen flag answers 409 unless the state is already present, in which case the call only finishes the workflow update (a retry after PARTIAL_SUCCESS) and the note is not recorded. For compact-license, a seen flag never 409s: the flag stays seen and is not re-moved, but any requested state not yet added is still written and the workflow updated — a reviewer can come back and add previously-unselected covered states while the flag is seen. A closed flag always answers 409. Returns 200 with a per-step outcome even when a follow-up step failed: status is FAILED when the practitioner record was not updated, PARTIAL_SUCCESS when it was but the flag or workflow step failed, SUCCESS otherwise. Safe to retry while the flag is not closed: a state already present is not written again and a seen flag is not moved again. Permission checks run before any write. Callers without the needs-verification permission get 404 for needsVerification and internal-only flags, as on GET /flags/{id}/details. Gated by flags.add-state-to-credential.enabled (default true); returns 404 while disabled.

📄️Get full flag details with history

Returns the full flag object plus its audit history trail (newest first), keyed by flag id. Includes the resolved certifyPractitionerId and history attachment metadata (no signed URLs). The payload carries both updatedAt (raw flags.updated_at — the change-detection signal for pollers) and updatedOn (the display value preferring metaData.sourceUpdateDate). Note comment-only history rows may not bump updatedAt, so clients should also diff the history array; status changes such as closures do bump it. Requires MONITORING_WORKFLOW_READ. npdb-data flags also carry an npdbPdf block; its signed URL is issued only to callers holding MONITORING_WORKFLOW_NPDB_PDF_READ, otherwise the block's status is PERMISSION_REQUIRED with no URL.

📄️Request regeneration of a flag's NPDB PDF

Enqueues a regeneration of the NPDB PDF backing the given npdb-data flag and returns 202 once the task is accepted. Intended as the recovery action for a terminally FAILED render (the drawer's Regenerate button); the render worker is the arbiter of the outcome — a READY or freshly in-flight document makes the task a no-op, so the call is safe to repeat. The client mints one idempotency key per logical request and reuses it on retries: the key correlates retries in server logs, and duplicate submissions are absorbed by the render worker's claim table — a retry can at most re-render the same digest-identical content, never a different document. The regenerated document becomes visible through the flag details response's npdbPdf block, which reports GENERATING while the render is in flight.

📄️Transition a single flag to a new 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.