Tenant context
Public API callers authenticate with a Bearer API key and send only the workflow fields documented for each endpoint. Tenant selection is handled by the key configuration, not by an ID field in the public request payload.
No tenant ID request field
Do not confuse QuickRCM tenant context with provider NPI, Tax ID, payer ID, facility ID, EHR ID, clearinghouse submitter ID, MRN, or payer claim number. Those identifiers may appear in module-specific workflows, but they do not select tenant context in public requests.
Tenant rules
| Rule | Detail |
|---|---|
| API key is authoritative | The key configuration selects the tenant context for public requests. Endpoint payloads should not ask callers to choose a tenant. |
| No public tenant override | If a request schema still exposes organizationId or a similar field, treat it as compatibility behavior until the endpoint page explicitly classifies it. |
| Wrong-org IDs do not disclose boundaries | A resource from another tenant should be treated as unavailable. Public clients should handle 403 or 404 without using the response to infer tenant existence. |
| Nested references need ownership checks | Patient, claim, file, payer, facility, appointment, job, batch, and artifact IDs must belong to the authenticated tenant before an endpoint uses them. |
| Response tenant echoes are not stable | Some generated responses currently expose organizationId or meta.organizationId. Stable examples and SDK fixtures must wait for the public tenant identifier policy. |
Actor and correlation caveats
| Topic | Guidance |
|---|---|
| API-key actor | Audit and support wording should attribute public API activity to the integration key unless an endpoint documents a distinct external requester. |
| Correlation IDs | Use endpoint-specific request or correlation fields when documented. Do not invent a universal header until the public contract declares one. |
| Metadata | Use metadata for non-sensitive reconciliation values only. Do not place PHI, secrets, tokens, raw vendor payloads, transcripts, or EDI content in metadata. |
Common workflow IDs
These IDs often appear in public API requests and responses.
| Field | Meaning | Example | Source | Confusion |
|---|---|---|---|---|
| providerNpi | 10-digit National Provider Identifier used in payer and claim workflows. | 1234567893 | Provider enrollment or organization billing settings. | Not a tenant, workspace, or payer identifier. |
| taxId | Provider or group tax identifier used for billing and payer workflows. | 12-3456789 | Billing configuration or provider enrollment records. | Sensitive value. Do not log it in application traces. |
| payerId | Clearinghouse or payer directory identifier. | 87726 | Payer directory, routing configuration, eligibility or claims setup. | Not the payer display name. |
| patientId | QuickRCM internal patient record ID. | 00000000-0000-4000-8000-000000000002 | Patient creation, patient list, EHR sync, or module response payloads. | Not necessarily the MRN unless explicitly mapped. |
| externalPatientId | Patient identifier from an EHR, PM system, or customer system. | athena-98323 | Customer source system or EHR integration mapping. | Use for source-system reconciliation; do not assume it is globally unique across organizations. |
| claimId | QuickRCM claim record ID. | 00000000-0000-4000-8000-000000000003 | Claim creation, claims list, denial, AR, or payment posting workflows. | Not the payer claim control number unless explicitly mapped. |
| batchId | Batch or grouped workflow identifier returned by bulk operations. | 00000000-0000-4000-8000-000000000004 | Bulk request response or generated processing metadata. | Use for polling or reconciliation when a module exposes batch status. |