Skip to main content

MonitoringWorkflow

APIs for managing monitoring workflows

📄️List monitoring workflows with filtering and pagination

Returns a paginated list of monitoring workflows for the authenticated tenant. Use this endpoint to browse or search workflows; use `GET /monitoring-workflows/{id}` when you already know a specific workflow ID. Supports two pagination modes: offset-based (`page`/`size`, default page 0, size 50) and cursor-based (`startAfterId` for forward, `endAtId` for backward). Supplying either cursor parameter switches the query to cursor-based pagination and overrides `page`/`size`; if both `startAfterId` and `endAtId` are supplied, `startAfterId` takes precedence and `endAtId` is ignored. Filtering is controlled by the `filter` query parameter, a URL-encoded JSON object mapping a field path to an operator (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, or `contains`; `contains` is only valid on string fields), e.g. {'data.monitoringStatus':{'eq':'IN_PROGRESS'}}. The `order` parameter accepts a JSON sort specification, e.g. {'createdAt':'desc'}. When `filter` is omitted, all workflows for the tenant are returned up to the page size. Requires the `MONITORING_WORKFLOW_READ` permission. The `tenant-id` header is mandatory. For callers without the `MONITORING_WORKFLOW_NEEDS_VERIFICATION_FLAG` permission, flags with status `needsVerification` are stripped from each workflow's flag arrays — the workflows themselves are still returned.

📄️Bulk-assign workflows to one or more users

Distributes multiple monitoring workflows evenly across the provided user IDs using round-robin assignment. Use this endpoint to assign many workflows in a single call instead of one at a time via `POST /monitoring-workflows/{id}/assignment`. The request body must supply either `workflowIds` or `filter` to identify which workflows to assign — at least one is required. Workflows currently in `REVIEWED_BY_CERTIFYOS` status are automatically excluded from assignment and appear in the response `failed` array. Requires one of: `MONITORING_WORKFLOW_ASSIGN`, `MONITORING_WORKFLOW_ASSIGN_SELF`, or `MONITORING_WORKFLOW_BULK_ASSIGN`. The `tenant-id` header is mandatory. Always returns HTTP 200, even when every individual assignment fails — check the `successful` and `failed` arrays for per-workflow outcomes.

📄️Bulk-update the monitoring status of multiple workflows

Transitions multiple monitoring workflows to the given `workflowStatus` in a single call. Use this endpoint for batch status changes; use `PUT /monitoring-workflows/{workflowId}/status` for a single workflow. Allowed `workflowStatus` values: `IN_PROGRESS`, `OUTREACH_IN_PROGRESS`, `DATA_MISSING`, `NO_ACTION_REQUIRED`, `REVIEWED_BY_CERTIFYOS`. The optional `description` field is a free-text note attached to the transition. Requires `MONITORING_WORKFLOW_UPDATE`. The `tenant-id` header is mandatory. Always returns HTTP 200, even when some workflows fail to transition — check the `successfulWorkflowIds` and `failures` arrays.

📄️Bulk-remove assignments from multiple workflows

Removes the current assignee from multiple monitoring workflows in one call. Use this endpoint for bulk unassignment; use `PATCH /monitoring-workflows/{id}/unassign` for a single workflow. The request body must supply either `workflowIds` or `filter` — at least one is required. Workflows in `REVIEWED_BY_CERTIFYOS` status are automatically excluded and appear in the response `failed` array. Requires all of: `MONITORING_WORKFLOW_ASSIGN`, `MONITORING_WORKFLOW_BULK_ASSIGN`, and `MONITORING_WORKFLOW_ASSIGN_SELF`. The `tenant-id` header is mandatory. Always returns HTTP 200, even when some unassignments fail — check the `successful` and `failed` arrays for per-workflow outcomes.

📄️Fetch a single monitoring workflow by ID

Returns a single monitoring workflow identified by `id`. Use this endpoint when you already have the workflow ID; use `GET /monitoring-workflows` to search or paginate. The `tenant-id` header is mandatory and scopes the lookup. The response is enriched with resolved display names (`verifiedByName`, `assignedByName`, `assignedToName`); records with a non-null `deletedAt` inside CRUD-enabled practitioner sections (e.g. `licenses`, `dea`) are filtered out; and, for callers without the `MONITORING_WORKFLOW_NEEDS_VERIFICATION_FLAG` permission, flags with status `needsVerification` are stripped from the flag arrays. Requires `MONITORING_WORKFLOW_READ`.

📄️Assign a monitoring workflow to a specific user

Assigns the monitoring workflow identified by `id` to the user given in `assignTo`. Use this endpoint for single-workflow assignment; use `POST /monitoring-workflows/assignments` for bulk assignment. The workflow must not currently be in `REVIEWED_BY_CERTIFYOS` status — if it is, this endpoint returns HTTP 400 with `{'error': '...'}` rather than the assignment result. Requires `MONITORING_WORKFLOW_ASSIGN` or `MONITORING_WORKFLOW_ASSIGN_SELF`. The `tenant-id` header is mandatory.

📄️Remove the assignment from a single workflow

Removes the current assignee from the monitoring workflow identified by `id`. Use this endpoint for single-workflow unassignment; use `PATCH /monitoring-workflows/unassign` for bulk unassignment. The workflow must not currently be in `REVIEWED_BY_CERTIFYOS` status — if it is, this endpoint returns HTTP 400 with `{'error': '...'}` rather than the unassignment result. Requires `MONITORING_WORKFLOW_ASSIGN` or `MONITORING_WORKFLOW_ASSIGN_SELF`. The `tenant-id` header is mandatory.

📄️Upload an attachment to a workflow section record

Attaches a file to a specific record within a monitoring workflow section. Use this endpoint to associate evidence or supporting files with a discrete record (e.g. a DEA row, a license row). The `id` form field identifies the target record using the format `{section}-{index}` (e.g. `dea-0`, `licenses-1`) — this value comes from the workflow's section data. The `file` form field is the binary file content and is required. The `expirationDate` form field is optional. Requires `MONITORING_WORKFLOW_DETAILS_UPDATE` and `MONITORING_WORKFLOW_DETAILS_ATTACHMENTS_CREATE`. The `tenant-id` header is mandatory.

📄️Trigger a CAQH or NPDB pipeline run for a workflow

Synchronously executes a data-fetch pipeline run for the specified monitoring workflow and returns once the run completes — the 200 response reflects actual completion, not just enqueue acknowledgment. Only `CAQH` and `NPDB` are valid values for `pipelineName`; `CREDENTIALING_WORKFLOW` appears in the shared pipeline-name enum but is explicitly rejected for monitoring workflows and returns 400. The tenant must have the corresponding pipeline (CAQH or NPDB) configured, or the run fails. Requires `MONITORING_WORKFLOW_PIPELINE_TRIGGER`. The `tenant-id` header is mandatory. Returns 404 when the workflow is not found.

📄️List pipeline runs for a monitoring workflow

Returns a paginated list of pipeline execution records (CAQH or NPDB) for the specified monitoring workflow. Use this endpoint to inspect run history; use `GET /monitoring-workflows/{workflowId}/pipeline-runs/{id}` to fetch a single run's detail. Supports offset-based pagination (`page`/`size`, default page 0, size 50) and cursor-based pagination (`cursor`); supplying `cursor` switches to cursor-based pagination and overrides `page`/`size`. The `filter` parameter accepts a JSON object using the same operators as `GET /monitoring-workflows` (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`), e.g. {'createdAt':{'gte':'2023-01-01T00:00:00Z'}}. The `order` parameter accepts a JSON sort specification, e.g. {'createdAt':'desc'}. When `includeSteps` is `true`, each run in the response includes its pipeline step breakdown; defaults to `false` when omitted. Requires `MONITORING_WORKFLOW_PIPELINE_TRIGGER`. The `tenant-id` header is mandatory. Returns 404 when the workflow does not exist or belongs to a different tenant.

📄️Mark a workflow section record as verified

Atomically marks a specific record within a monitoring workflow section as verified by recording the current user as `verifiedBy` and the current server timestamp as `verifiedDate`. Only the verification fields are modified; all other record data is left unchanged. Use this endpoint after reviewing a record and confirming the data is accurate. Verification is not restricted to a fixed set of sections — it works for any section present in the workflow's practitioner data (including `nppes`). Requires both `MONITORING_WORKFLOW_DETAILS_UPDATE` and `MONITORING_WORKFLOW_DETAILS_VERIFY`. The `tenant-id` header is mandatory.

📄️Transition a monitoring workflow to a new status

Updates the `monitoringStatus` of a single workflow to the given target status. Use this endpoint for individual status transitions; use `PUT /monitoring-workflows/bulk/status` for batch transitions. Allowed `workflowStatus` values: `IN_PROGRESS`, `OUTREACH_IN_PROGRESS`, `DATA_MISSING`, `NO_ACTION_REQUIRED`, `REVIEWED_BY_CERTIFYOS`. The optional `description` field is a free-text note attached to the transition. Requires `MONITORING_WORKFLOW_UPDATE`. The `tenant-id` header is mandatory.

📄️Replace all supporting documents for a workflow

Replaces the entire supporting documents collection for the specified monitoring workflow with the provided array (full-replace PUT semantics). Use this endpoint to set the complete desired state in one call; to add a single new document without touching existing ones, use `POST /monitoring-workflows/{workflowId}/supporting-documents`. Supplying an empty array removes all supporting documents from the workflow — this is irreversible via this endpoint. Each element must supply `fileUrl`, `fileType`, and `originalFileName` (all required); `createdAt`, `createdBy`, `state`, `expirationDate`, and `source` are optional. Requires `MONITORING_WORKFLOW_DETAILS_CREATE`, `MONITORING_WORKFLOW_DETAILS_UPDATE`, and `MONITORING_WORKFLOW_DETAILS_SUPPORTING_DOCUMENTS_CREATE`. The `tenant-id` header is mandatory.

📄️Upload a new supporting document to a workflow

Uploads a single supporting document file and appends it to the workflow's supporting documents collection. Use this endpoint to add one document without affecting the others; use `PUT /monitoring-workflows/{workflowId}/supporting-documents` to replace the entire collection. The request is a multipart/form-data upload: `file` is required (the binary content); `fileType` is required (e.g. 'Medical License'); `state` is optional; `expirationDate` is optional and must be in `YYYY-MM-DD` format when provided — an invalid format returns 400. Requires `MONITORING_WORKFLOW_DETAILS_CREATE`, `MONITORING_WORKFLOW_DETAILS_UPDATE`, and `MONITORING_WORKFLOW_DETAILS_SUPPORTING_DOCUMENTS_CREATE`. The `tenant-id` header is mandatory.

📄️Add a new record to a monitoring workflow section

Creates a new record within the specified section of a monitoring workflow and returns the created record with its server-assigned index. Use this endpoint to add manually-entered credentialing data (e.g. a new license, a new DEA registration) to a workflow. The request body schema varies by section — supply the fields for the `sectionName` given. Requires `MONITORING_WORKFLOW_DETAILS_CREATE`. The `tenant-id` header is mandatory. Generic endpoint supporting sections: appVerifications, boardCertifications, cds, compactLicenses, dea, deathMasterMatches, educationTraining, hospitalAffiliations, licenses, licensureActions, malpracticeInsurance, npdbReports, nppes, performanceIndicators, practiceLocations, professionalIds, sanctions, siteVisits, specialties, supportingDocuments

📄️Partially update a record in a workflow section

Applies a partial update (merge-patch semantics) to a specific record within a monitoring workflow section, returning the updated record. Use this endpoint to modify individual fields of an existing record; use `POST /monitoring-workflows/{workflowId}/{sectionName}` to add a new record. Only fields included in the request body are updated; omitted fields retain their existing values. Requires `MONITORING_WORKFLOW_DETAILS_UPDATE`. The `tenant-id` header is mandatory. Generic endpoint supporting all CRUD-enabled sections: appVerifications, boardCertifications, cds, compactLicenses, dea, educationTraining, hospitalAffiliations, licenses, licensureActions, malpracticeInsurance, npdbReports, nppes, performanceIndicators, practiceLocations, professionalIds, sanctions, siteVisits, specialties, supportingDocuments

📄️Soft-delete a record from a workflow section

Soft-deletes the specified record from a monitoring workflow section by setting its `deletedAt` timestamp; the record is not physically removed from storage. Use this endpoint to remove a record that was entered in error or is no longer applicable. Requires `MONITORING_WORKFLOW_DETAILS_DELETE`. The `tenant-id` header is mandatory. Generic endpoint supporting all CRUD-enabled sections: appVerifications, boardCertifications, cds, compactLicenses, dea, educationTraining, hospitalAffiliations, licenses, licensureActions, malpracticeInsurance, npdbReports, nppes, performanceIndicators, practiceLocations, professionalIds, sanctions, siteVisits, specialties, supportingDocuments