Side-effect modes
Endpoint pages must say what a request does now and what it does not do. This prevents queue-only, local, simulated, or metadata behavior from being mistaken for live external execution.
External reads count too
Payer, EHR, clearinghouse, SFTP, portal, LLM, OCR, browser automation, file, payment, and communication activity should be treated as side-effect-sensitive until the route is explicitly approved.
Mode rules
| Mode | Meaning | Current rule |
|---|---|---|
| Read-only | Reads tenant-scoped QuickRCM data only unless an endpoint explicitly states an external lookup. | Safe for guides only after route status and PHI-safe response evidence are clear. |
| Local write | Mutates QuickRCM records. | Does not imply payer, EHR, clearinghouse, payment, file, or communication execution. |
| Validate-only | Checks request shape, ownership, business rules, or downstream readiness without committing the requested workflow result. | Document only if the endpoint exposes the mode and evidence shows whether any durable validation record is created. |
| Dry-run or simulate | Returns preview, estimate, simulation, route decision, or generated output without approved live execution. | Describe as compatibility behavior, not production execution. |
| Queue or async | Creates or references queued work, often with HTTP 202. | Queueing is not completion; status and terminal states must be endpoint-specific. |
| File or artifact | Touches documents, reports, PDFs, transcripts, EDI, OCR, or generated artifacts. | Use metadata-only examples until file governance is approved. |
| Payment, communication, external, or credentialed | May affect money, credits, notices, credentials, webhooks, SFTP, EHRs, payers, or vendors. | Blocked from public recipes until product, security, and release evidence close. |
External systems and disclosures
| Class | Examples | Guidance |
|---|---|---|
| Payer or clearinghouse | Eligibility, claim submission, claim status, ERA retrieval, COB, prior authorization. | Do not imply live transaction execution unless side-effect evidence and route status both approve it. |
| EHR or portal | FHIR sync, document writeback, browser automation, credentialed portal tasks. | Treat reads and disclosures as side-effect-sensitive, not only writes. |
| AI, OCR, transcription | Coding, scribe, EOB conversion, document extraction, prevention signals. | Separate local job creation from model execution, generated output, and artifact storage. |
| Payments or communications | Card payments, refunds, statements, collections notices, emails, SMS, calls. | Block from recipes until workflow state, consent, audit, and rollback semantics are documented. |
Safe wording for docs and examples
| Avoid | Prefer |
|---|---|
| This submits the claim. | This creates or queues a claim workflow record unless the endpoint page explicitly states live clearinghouse submission. |
| The payer decision is final. | The response reflects the endpoint's recorded or returned status; payer source-of-truth rules are endpoint-specific. |
| Dry-run has no effects. | Dry-run does not perform the documented live action; any validation logs, usage, or generated artifacts must be endpoint-specific. |
| Queued means complete. | HTTP 202 means accepted or scheduled. Completion requires endpoint-specific status evidence. |