---
title: "Run synchronous flag calculation for a monitoring workflow"
method: POST
path: "/flag-calculator"
tags: ["FlagCalculator"]
---

# Run synchronous flag calculation for a monitoring workflow

`POST /flag-calculator`

Evaluates practitioner data against a monitoring workflow and creates, updates, or deactivates flags based on the difference from the current flag state, returning counts of flags created, updated, deactivated, and a total. Call this endpoint to trigger on-demand, synchronous flag calculation for a single monitoring workflow — do not use it for bulk or event-driven recalculation, which separate Kafka-driven consumers handle instead. If the workflow's status is REVIEWED_BY_CERTIFYOS, the endpoint accepts the request but performs no flag evaluation, does not update lastFlagCalculationTimestamp, and returns all-zero counts (verified: calculateFlagsWithTenantId returns early for workflows whose status is in MonitoringWorkflowConstants.COMPLETED_WORKFLOW_STATUSES). The monitoring workflow identified by monitoringWorkflowId must already exist and belong to the tenant identified by the required tenant-id header, or the call returns 404. Pass sections in the request body to limit calculation to a subset of the accepted section names; omitting it or passing an empty array calculates flags across all sections, and any unrecognized section name is silently ignored rather than rejected. The X-Monitoring-Api-Key header is only enforced while the monitoring.api-key-enabled kill-switch is turned on (off by default) — when enforced, a missing or mismatched key returns 401. On a real (non-no-op) evaluation, lastFlagCalculationTimestamp is written back to the monitoring workflow record. Repeated calls re-evaluate flags from current practitioner data each time — the call is safe to retry after a transient error, but successive successful calls may produce different flag counts if the underlying practitioner data changed between calls.

## Headers

- `X-Monitoring-Api-Key` string
- `tenant-id` string, required
- `user-id` string

## Request body

- FlagCalculatorRequest — Request body for POST /flag-calculator, identifying the monitoring workflow to evaluate and, optionally, which practitioner data sections to limit the calculation to.
  - `monitoringWorkflowId` string, required — ID of the monitoring workflow to calculate flags for. Must reference a workflow that already exists and belongs to the tenant identified by the tenant-id header, or the call returns 404.
  - `sections` string[] — Practitioner data sections to limit flag calculation to. Valid values: appVerifications, boardCertifications, cds, dea, educationTraining, hospitalAffiliations, licenses, licensureActions, malpracticeInsurance, npdbReports, nppes, performanceIndicators, practiceLocations, professionalIds, sanctions, siteVisits, specialties, supportingDocuments. If omitted or empty, flags are calculated across all sections. Any value outside this list is silently ignored rather than rejected — it will not cause a 400 and will not match any flags.

## Response `200`

A summary of the flag calculation outcome: how many flags were created, updated, and deactivated, plus the resulting total. All four counters are 0 when the workflow's status is REVIEWED_BY_CERTIFYOS — flag evaluation is skipped for that status (see the operation description).

- FlagCalculatorResponse — Result of a POST /flag-calculator call: how many flags were created, updated, and deactivated, plus the resulting total. All four counters are 0 when the workflow's status is REVIEWED_BY_CERTIFYOS, since flag evaluation is skipped for that status.
  - `flagsCreated` integer — Number of flags newly created during this evaluation. Non-negative integer; 0 when the workflow's status is REVIEWED_BY_CERTIFYOS (no-op path).
  - `flagsUpdated` integer — Number of existing flags whose state changed during this evaluation. Non-negative integer; 0 when the workflow's status is REVIEWED_BY_CERTIFYOS (no-op path).
  - `flagsDeactivated` integer — Number of previously active flags deactivated during this evaluation. Non-negative integer; 0 when the workflow's status is REVIEWED_BY_CERTIFYOS (no-op path).
  - `totalFlags` integer — Total number of active flags on the workflow after this evaluation completed. Non-negative integer; 0 when the workflow's status is REVIEWED_BY_CERTIFYOS (no-op path).
  - `monitoringWorkflowId` string — ID of the monitoring workflow this result belongs to; echoes the monitoringWorkflowId from the request.

## Other responses

- `400` — Bad Request - the request body is missing monitoringWorkflowId or is otherwise malformed. Verify the request body matches the FlagCalculatorRequest schema.
- `401` — Unauthorized - the X-Monitoring-Api-Key header is missing or does not match the configured monitoring.api-key, and the monitoring.api-key-enabled kill-switch is turned on. Verify the header value against the configured key.
- `404` — Not Found - no monitoring workflow exists with the given monitoringWorkflowId for the tenant identified by tenant-id. Verify the workflow ID and the tenant-id header.
- `500` — Internal Server Error - an unexpected error occurred while calculating flags. Retry the request; if the error persists, contact support.

---

[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)