Sign in
latestOpenAPI 3.1.02026-08-194237902.5 MB

563848e0ecc0

FlagCalculator

Run synchronous flag calculation for a monitoring workflow

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.

post/flag-calculator

Headers

X-Monitoring-Api-Keystring

Shared secret checked against the monitoring.api-key configuration property. Only enforced while the monitoring.api-key-enabled kill-switch is turned on (off by default); when enforcement is enabled, a missing or mismatched key returns 401.

tenant-idstring required

Tenant ID that the monitoring workflow identified by monitoringWorkflowId must belong to; required on every call.

user-idstring

Optional ID of the calling user, used to attribute service-to-service calls. When omitted, no user context is attached to the operation.

Request body

monitoringWorkflowIdstring 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.

sectionsstring[]

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.

Example request

{
  "monitoringWorkflowId": "mw_1234567890",
  "sections": [
    "licenses",
    "educationTraining"
  ]
}

Response

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

flagsCreatedinteger

Number of flags newly created during this evaluation. Non-negative integer; 0 when the workflow's status is REVIEWED_BY_CERTIFYOS (no-op path).

flagsUpdatedinteger

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

flagsDeactivatedinteger

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

totalFlagsinteger

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

monitoringWorkflowIdstring

ID of the monitoring workflow this result belongs to; echoes the monitoringWorkflowId from the request.

Example response

{
  "flagsCreated": 5,
  "flagsUpdated": 3,
  "flagsDeactivated": 2,
  "totalFlags": 8,
  "monitoringWorkflowId": "mw_1234567890"
}