{"openapi":"3.1.0","info":{"title":"QuickRCM Public API","version":"1.0.0"},"servers":[{"url":"https://dev-api.quickintell.com"}],"components":{"schemas":{},"parameters":{},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}}},"paths":{"/api/v1/adr/requests":{"get":{"operationId":"listAdrRequests","summary":"List ADR requests","description":"Returns ADR requests owned by the authenticated API key organization, with filters for status, ADR type, claim, assignee, overdue state, requestor entity, submission method, received date, response deadline, and search text.\n\n### When to use\nUse this endpoint to build ADR worklists, find requests approaching response deadlines, reconcile documentation requests, or select an ADR before viewing detail or recording a lifecycle event.\n\n### Before calling\nAuthenticate with a tenant-scoped API key that has adr:read or adr:write scope. Decide the narrowest useful filters and use skip/take pagination for production list calls.\n\n### Request guidance\nUse bounded pagination; take defaults to 25 and is capped at 100. overdueOnly is the string true or false. Date filters accept ISO 8601 date or datetime strings. Date-only filter values are interpreted at 00:00:00.000Z on that UTC date, including upper bounds, so callers that need the whole final day should send an explicit end-of-day datetime. searchTerm matches local trackingNumber, requestorName, or requestorEntity, so avoid logging raw search values if they contain sensitive context.\n\n### Request notes\n- Use status, adrType, claimId, overdueOnly, and date filters to avoid broad PHI-heavy worklists.\n- Use skip and take together; take must remain between 1 and 100.\n- The API key selects the organization; do not send organizationId as a public tenant selector.\n- For receivedDateTo or responseDeadlineTo date-only filters, send an explicit end-of-day timestamp if records later on that day should be included.\n\n### Response semantics\nThe response contains local QuickRCM ADR records plus document-reference metadata, total, skip, and take. Records are ordered by responseDeadline ascending in the handler. A listed ADR is not proof that documents have been externally submitted or accepted by a payer.\n\n### Response notes\n- data.adrs contains local ADR workflow records and document metadata.\n- documents are references only; they are not binary file contents.\n- submission fields reflect local tracking state, not payer adjudication.\n\n### Errors and retries\nTreat 400 as invalid filters, 401 as missing or invalid bearer credentials, 403 as insufficient ADR scope, and 429 as a backoff signal. Do not retry authorization failures without changing credentials or scopes.\n\n### Error notes\n- 400 can indicate malformed ISO dates, invalid enum values, or pagination bounds.\n- 429 should be retried with backoff.\n- 401 and 403 require credential or scope correction.\n","tags":["ADR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["ADR_RECEIVED","ADR_IN_PROGRESS","ADR_DOCS_ASSEMBLED","ADR_SUBMITTED","ADR_OUTCOME_APPROVED","ADR_OUTCOME_DENIED","ADR_OVERDUE","ADR_EXPIRED"]},"required":false,"name":"status","in":"query","description":"Optional ADR workflow status filter. Valid values include ADR_RECEIVED, ADR_IN_PROGRESS, ADR_DOCS_ASSEMBLED, ADR_SUBMITTED, ADR_OUTCOME_APPROVED, ADR_OUTCOME_DENIED, ADR_OVERDUE, and ADR_EXPIRED."},{"schema":{"type":"string","enum":["ADR_PREPAYMENT_REVIEW","ADR_POST_PAYMENT_REVIEW","ADR_RAC_REQUEST","ADR_PAYER_CLINICAL_REVIEW","ADR_PRIOR_AUTH_SUPPORT","ADR_HOSPICE_AUDIT"]},"required":false,"name":"adrType","in":"query","description":"Optional ADR request category filter. Public enum values include prepayment review, post-payment review, RAC request, payer clinical review, prior-authorization support, and hospice audit categories."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"claimId","in":"query","description":"Optional exact QuickRCM claim identifier filter. The list still returns only ADRs in the API key organization."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"assignedTo","in":"query","description":"Optional exact QuickRCM assignee identifier filter for local ADR ownership or queue routing."},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"overdueOnly","in":"query","description":"String boolean filter. Use true to return only records whose local isOverdue flag is true."},{"schema":{"type":"string","minLength":1,"maxLength":160},"required":false,"name":"requestorEntity","in":"query","description":"Optional exact requester entity filter, such as the payer, Centers for Medicare & Medicaid Services (CMS) contractor, reviewer, or internal requester label captured on the ADR."},{"schema":{"type":"string","enum":["ATT_ELECTRONIC_275","ATT_PWK_LOOP","ATT_PAYER_PORTAL","ATT_FAX","ATT_MAIL","ATT_AVAILITY_ATTACHMENTS"]},"required":false,"name":"submissionMethod","in":"query","description":"Optional submission-channel enum filter. Valid values include ATT_ELECTRONIC_275, ATT_PWK_LOOP, ATT_PAYER_PORTAL, ATT_FAX, ATT_MAIL, and ATT_AVAILITY_ATTACHMENTS."},{"schema":{"type":"string","minLength":1},"required":false,"name":"receivedDateFrom","in":"query","description":"Inclusive lower bound for receivedDate. Use an ISO 8601 date or datetime string; date-only values start at 00:00:00.000Z."},{"schema":{"type":"string","minLength":1},"required":false,"name":"receivedDateTo","in":"query","description":"Inclusive upper bound for receivedDate. Date-only values are treated as 00:00:00.000Z on that UTC date, so send an explicit end-of-day datetime to include the full final day."},{"schema":{"type":"string","minLength":1},"required":false,"name":"responseDeadlineFrom","in":"query","description":"Inclusive lower bound for responseDeadline. Use an ISO 8601 date or datetime string; date-only values start at 00:00:00.000Z."},{"schema":{"type":"string","minLength":1},"required":false,"name":"responseDeadlineTo","in":"query","description":"Inclusive upper bound for responseDeadline. Date-only values are treated as 00:00:00.000Z on that UTC date, so send an explicit end-of-day datetime to include the full final day."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"searchTerm","in":"query","description":"Free-text filter across trackingNumber, requestorName, and requestorEntity. Keep search terms out of logs when they include sensitive workflow context."},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"skip","in":"query","description":"Zero-based number of records to skip for pagination. Defaults to 0."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"take","in":"query","description":"Maximum records to return for this page. Defaults to 25 and cannot exceed 100."}],"responses":{"200":{"description":"ADR request list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"adrs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":"string"},"adrType":{"type":"string","enum":["ADR_PREPAYMENT_REVIEW","ADR_POST_PAYMENT_REVIEW","ADR_RAC_REQUEST","ADR_PAYER_CLINICAL_REVIEW","ADR_PRIOR_AUTH_SUPPORT","ADR_HOSPICE_AUDIT"]},"status":{"type":"string","enum":["ADR_RECEIVED","ADR_IN_PROGRESS","ADR_DOCS_ASSEMBLED","ADR_SUBMITTED","ADR_OUTCOME_APPROVED","ADR_OUTCOME_DENIED","ADR_OVERDUE","ADR_EXPIRED"]},"receivedDate":{"type":"string","format":"date-time"},"responseDeadline":{"type":"string","format":"date-time"},"isOverdue":{"type":"boolean"},"requestedDocTypes":{"type":"array","items":{"type":"string"}},"requestorName":{"type":["string","null"]},"requestorEntity":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"submissionMethod":{"type":["string","null"],"enum":["ATT_ELECTRONIC_275","ATT_PWK_LOOP","ATT_PAYER_PORTAL","ATT_FAX","ATT_MAIL","ATT_AVAILITY_ATTACHMENTS"]},"submissionTrackingId":{"type":["string","null"]},"outcomeDate":{"type":["string","null"],"format":"date-time"},"recoveredAmount":{"type":["string","null"]},"assignedTo":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","documentType","title","source","externalDocumentId","createdAt"]}}},"required":["id","organizationId","claimId","adrType","status","receivedDate","responseDeadline","isOverdue","requestedDocTypes","requestorName","requestorEntity","trackingNumber","submittedAt","submissionMethod","submissionTrackingId","outcomeDate","recoveredAmount","assignedTo","createdAt","updatedAt","documents"]}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["adrs","total","skip","take"]}},"required":["success","data"]},"example":{"success":true,"data":{"adrs":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","adrType":"ADR_PREPAYMENT_REVIEW","status":"ADR_RECEIVED","receivedDate":"2026-06-08T10:15:30Z","responseDeadline":"2026-06-08T10:15:30Z","isOverdue":true,"requestedDocTypes":["example-requesteddoctypes"],"requestorName":"Example adr_request","requestorEntity":"example-requestorentity","trackingNumber":"example-trackingnumber","submittedAt":"2026-06-08T10:15:30Z","submissionMethod":"ATT_ELECTRONIC_275","submissionTrackingId":"00000000-0000-4000-8000-000000000001","outcomeDate":"2026-06-08T10:15:30Z","recoveredAmount":"example-recoveredamount","assignedTo":"example-assignedto","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","documents":[{"id":"00000000-0000-4000-8000-000000000001","documentType":"example-documenttype","title":"Example adr_request","source":"example-source","externalDocumentId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z"}]}],"total":1,"skip":1,"take":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createAdrRequest","summary":"Create ADR request","description":"Creates a local, claim-linked ADR request after verifying that the claim belongs to the authenticated organization.\n\n### When to use\nUse this when an external payer, Centers for Medicare & Medicaid Services (CMS), a Recovery Audit Contractor (RAC), or an internal intake workflow identifies a documentation request that should be tracked against an existing QuickRCM claim.\n\n### Before calling\nResolve claimId from QuickRCM in the same tenant. Choose the ADR type, received date, response deadline, requested document types, and any requester tracking number. Use idempotencyKey only for safe retries when no requester tracking number exists.\n\n### Request guidance\nSend claimId, adrType, receivedDate, responseDeadline, and at least one requestedDocType. receivedDate and responseDeadline must be valid ISO 8601 date or datetime strings. requestedDocTypes accepts 1 to 50 non-empty values. idempotencyKey is capped at 200 characters and must not contain PHI.\n\n### Request notes\n- The API key selects the organization; body organizationId is not a public tenant selector.\n- Use trackingNumber when the requester provides a stable reference.\n- Use idempotencyKey for network retries of tracking-less ADR intake and keep it free of PHI.\n\n### Response semantics\nA new ADR returns 201 with a local ADR record. An idempotent retry returns 200 with the existing ADR when the same organization, claimId, and trackingNumber match, or when a tracking-less retry uses the same idempotencyKey. New records start in ADR_RECEIVED and include an isOverdue flag computed from responseDeadline.\n\n### Response notes\n- 201 means a new local ADR was created.\n- 200 means an existing ADR was returned for an idempotent retry.\n- For tracking-less idempotency, the internal marker is not returned as a public trackingNumber.\n\n### Errors and retries\nFix 400 validation errors before retrying. A 404 means the claim could not be resolved inside the API key organization. Reuse the same idempotencyKey only for the same create attempt.\n\n### Error notes\n- 400 can indicate invalid dates, missing requestedDocTypes, or invalid enum values.\n- 404 means claimId is missing or unavailable to this tenant.\n- 429 should be retried with backoff and the same idempotency key when applicable.\n","tags":["ADR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimId":{"type":"string","minLength":1,"description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."},"adrType":{"type":"string","enum":["ADR_PREPAYMENT_REVIEW","ADR_POST_PAYMENT_REVIEW","ADR_RAC_REQUEST","ADR_PAYER_CLINICAL_REVIEW","ADR_PRIOR_AUTH_SUPPORT","ADR_HOSPICE_AUDIT"],"description":"ADR category enum used to classify the request workflow, including prepayment review, post-payment review, Recovery Audit Contractor (RAC) request, payer clinical review, prior-authorization support, and hospice audit values."},"receivedDate":{"type":"string","minLength":1,"description":"Date or datetime when the ADR request was received. Must be a valid ISO 8601 date or datetime string.","example":"2026-06-08"},"responseDeadline":{"type":"string","minLength":1,"description":"Date or datetime by which the response is due. Must be a valid ISO 8601 date or datetime string.","example":"2026-06-30"},"requestedDocTypes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":50,"description":"Array of requested supporting document categories. Use stable operational labels such as clinical_notes or operative_report when your workflow uses those values."},"requestorName":{"type":"string","minLength":1,"maxLength":160,"description":"Optional staff-readable requester name or department label. Avoid unnecessary personal details."},"requestorEntity":{"type":"string","minLength":1,"maxLength":160,"description":"Optional requester organization, reviewer, CMS contractor, RAC, or payer label."},"trackingNumber":{"type":"string","minLength":1,"maxLength":120,"description":"Requester, portal, or internal ADR request tracking reference. It is used with claimId for duplicate detection when provided."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-supplied retry key for tracking-less ADR intake. Reuse only for safe retries of the same request and do not include PHI."},"assignedTo":{"type":"string","minLength":1,"maxLength":128,"description":"QuickRCM user identifier for local assignment when known. It should refer to a user in the same organization."}},"required":["claimId","adrType","receivedDate","responseDeadline","requestedDocTypes"]},"example":{"claimId":"00000000-0000-4000-8000-000000000001","adrType":"ADR_PREPAYMENT_REVIEW","receivedDate":"2026-06-08","responseDeadline":"2026-06-30","requestedDocTypes":["example-requesteddoctypes"],"requestorName":"Example adr_request","requestorEntity":"example-requestorentity","trackingNumber":"example-trackingnumber","idempotencyKey":"example-idempotencykey","assignedTo":"example-assignedto"}}},"description":"Send claimId, adrType, receivedDate, responseDeadline, and at least one requestedDocType. receivedDate and responseDeadline must be valid ISO 8601 date or datetime strings. requestedDocTypes accepts 1 to 50 non-empty values. idempotencyKey is capped at 200 characters and must not contain PHI."},"responses":{"200":{"description":"Existing ADR request returned for an idempotent retry","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":"string"},"adrType":{"type":"string","enum":["ADR_PREPAYMENT_REVIEW","ADR_POST_PAYMENT_REVIEW","ADR_RAC_REQUEST","ADR_PAYER_CLINICAL_REVIEW","ADR_PRIOR_AUTH_SUPPORT","ADR_HOSPICE_AUDIT"]},"status":{"type":"string","enum":["ADR_RECEIVED","ADR_IN_PROGRESS","ADR_DOCS_ASSEMBLED","ADR_SUBMITTED","ADR_OUTCOME_APPROVED","ADR_OUTCOME_DENIED","ADR_OVERDUE","ADR_EXPIRED"]},"receivedDate":{"type":"string","format":"date-time"},"responseDeadline":{"type":"string","format":"date-time"},"isOverdue":{"type":"boolean"},"requestedDocTypes":{"type":"array","items":{"type":"string"}},"requestorName":{"type":["string","null"]},"requestorEntity":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"submissionMethod":{"type":["string","null"],"enum":["ATT_ELECTRONIC_275","ATT_PWK_LOOP","ATT_PAYER_PORTAL","ATT_FAX","ATT_MAIL","ATT_AVAILITY_ATTACHMENTS"]},"submissionTrackingId":{"type":["string","null"]},"outcomeDate":{"type":["string","null"],"format":"date-time"},"recoveredAmount":{"type":["string","null"]},"assignedTo":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","documentType","title","source","externalDocumentId","createdAt"]}}},"required":["id","organizationId","claimId","adrType","status","receivedDate","responseDeadline","isOverdue","requestedDocTypes","requestorName","requestorEntity","trackingNumber","submittedAt","submissionMethod","submissionTrackingId","outcomeDate","recoveredAmount","assignedTo","createdAt","updatedAt","documents"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","adrType":"ADR_PREPAYMENT_REVIEW","status":"ADR_RECEIVED","receivedDate":"2026-06-08T10:15:30Z","responseDeadline":"2026-06-08T10:15:30Z","isOverdue":true,"requestedDocTypes":["example-requesteddoctypes"],"requestorName":"Example adr_request","requestorEntity":"example-requestorentity","trackingNumber":"example-trackingnumber","submittedAt":"2026-06-08T10:15:30Z","submissionMethod":"ATT_ELECTRONIC_275","submissionTrackingId":"00000000-0000-4000-8000-000000000001","outcomeDate":"2026-06-08T10:15:30Z","recoveredAmount":"example-recoveredamount","assignedTo":"example-assignedto","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","documents":[{"id":"00000000-0000-4000-8000-000000000001","documentType":"example-documenttype","title":"Example adr_request","source":"example-source","externalDocumentId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z"}]}}}}},"201":{"description":"ADR request created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":"string"},"adrType":{"type":"string","enum":["ADR_PREPAYMENT_REVIEW","ADR_POST_PAYMENT_REVIEW","ADR_RAC_REQUEST","ADR_PAYER_CLINICAL_REVIEW","ADR_PRIOR_AUTH_SUPPORT","ADR_HOSPICE_AUDIT"]},"status":{"type":"string","enum":["ADR_RECEIVED","ADR_IN_PROGRESS","ADR_DOCS_ASSEMBLED","ADR_SUBMITTED","ADR_OUTCOME_APPROVED","ADR_OUTCOME_DENIED","ADR_OVERDUE","ADR_EXPIRED"]},"receivedDate":{"type":"string","format":"date-time"},"responseDeadline":{"type":"string","format":"date-time"},"isOverdue":{"type":"boolean"},"requestedDocTypes":{"type":"array","items":{"type":"string"}},"requestorName":{"type":["string","null"]},"requestorEntity":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"submissionMethod":{"type":["string","null"],"enum":["ATT_ELECTRONIC_275","ATT_PWK_LOOP","ATT_PAYER_PORTAL","ATT_FAX","ATT_MAIL","ATT_AVAILITY_ATTACHMENTS"]},"submissionTrackingId":{"type":["string","null"]},"outcomeDate":{"type":["string","null"],"format":"date-time"},"recoveredAmount":{"type":["string","null"]},"assignedTo":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","documentType","title","source","externalDocumentId","createdAt"]}}},"required":["id","organizationId","claimId","adrType","status","receivedDate","responseDeadline","isOverdue","requestedDocTypes","requestorName","requestorEntity","trackingNumber","submittedAt","submissionMethod","submissionTrackingId","outcomeDate","recoveredAmount","assignedTo","createdAt","updatedAt","documents"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","adrType":"ADR_PREPAYMENT_REVIEW","status":"ADR_RECEIVED","receivedDate":"2026-06-08T10:15:30Z","responseDeadline":"2026-06-08T10:15:30Z","isOverdue":true,"requestedDocTypes":["example-requesteddoctypes"],"requestorName":"Example adr_request","requestorEntity":"example-requestorentity","trackingNumber":"example-trackingnumber","submittedAt":"2026-06-08T10:15:30Z","submissionMethod":"ATT_ELECTRONIC_275","submissionTrackingId":"00000000-0000-4000-8000-000000000001","outcomeDate":"2026-06-08T10:15:30Z","recoveredAmount":"example-recoveredamount","assignedTo":"example-assignedto","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","documents":[{"id":"00000000-0000-4000-8000-000000000001","documentType":"example-documenttype","title":"Example adr_request","source":"example-source","externalDocumentId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/adr/requests/{adrId}":{"get":{"operationId":"getAdrRequest","summary":"Get ADR request","description":"Returns one ADR request when the ADR identifier resolves inside the organization selected by the bearer API key.\n\n### When to use\nUse this after listAdrRequests, createAdrRequest, a queue item, or another trusted QuickRCM response gives you an adrId.\n\n### Before calling\nConfirm the adrId came from the same tenant context as the API key. Read calls accept adr:read or adr:write scope.\n\n### Request guidance\nPass only adrId in the path. Do not include organizationId, payer credentials, raw EDI, document bytes, or storage keys in the request.\n\n### Request notes\n- Use adrId from a trusted QuickRCM response.\n- Do not guess ADR identifiers across tenants.\n\n### Response semantics\nThe response is the local ADR record, including requested document types, submission tracking fields, outcome fields, and document-reference metadata.\n\n### Response notes\n- The response includes documents as metadata references only.\n- trackingNumber can be null when a tracking-less public create used an internal idempotency marker.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization ADR context unless a prior create response proves the record exists. Retry transient 5xx responses with normal backoff.\n\n### Error notes\n- 404 can mean the ADR is missing or belongs to a different organization.\n- 401 or 403 indicates API key or scope correction is required.\n","tags":["ADR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"adrId","in":"path","description":"QuickRCM Additional Documentation Request identifier in the path. It must belong to the organization selected by the bearer API key."}],"responses":{"200":{"description":"ADR request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":"string"},"adrType":{"type":"string","enum":["ADR_PREPAYMENT_REVIEW","ADR_POST_PAYMENT_REVIEW","ADR_RAC_REQUEST","ADR_PAYER_CLINICAL_REVIEW","ADR_PRIOR_AUTH_SUPPORT","ADR_HOSPICE_AUDIT"]},"status":{"type":"string","enum":["ADR_RECEIVED","ADR_IN_PROGRESS","ADR_DOCS_ASSEMBLED","ADR_SUBMITTED","ADR_OUTCOME_APPROVED","ADR_OUTCOME_DENIED","ADR_OVERDUE","ADR_EXPIRED"]},"receivedDate":{"type":"string","format":"date-time"},"responseDeadline":{"type":"string","format":"date-time"},"isOverdue":{"type":"boolean"},"requestedDocTypes":{"type":"array","items":{"type":"string"}},"requestorName":{"type":["string","null"]},"requestorEntity":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"submissionMethod":{"type":["string","null"],"enum":["ATT_ELECTRONIC_275","ATT_PWK_LOOP","ATT_PAYER_PORTAL","ATT_FAX","ATT_MAIL","ATT_AVAILITY_ATTACHMENTS"]},"submissionTrackingId":{"type":["string","null"]},"outcomeDate":{"type":["string","null"],"format":"date-time"},"recoveredAmount":{"type":["string","null"]},"assignedTo":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","documentType","title","source","externalDocumentId","createdAt"]}}},"required":["id","organizationId","claimId","adrType","status","receivedDate","responseDeadline","isOverdue","requestedDocTypes","requestorName","requestorEntity","trackingNumber","submittedAt","submissionMethod","submissionTrackingId","outcomeDate","recoveredAmount","assignedTo","createdAt","updatedAt","documents"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","adrType":"ADR_PREPAYMENT_REVIEW","status":"ADR_RECEIVED","receivedDate":"2026-06-08T10:15:30Z","responseDeadline":"2026-06-08T10:15:30Z","isOverdue":true,"requestedDocTypes":["example-requesteddoctypes"],"requestorName":"Example adr_request","requestorEntity":"example-requestorentity","trackingNumber":"example-trackingnumber","submittedAt":"2026-06-08T10:15:30Z","submissionMethod":"ATT_ELECTRONIC_275","submissionTrackingId":"00000000-0000-4000-8000-000000000001","outcomeDate":"2026-06-08T10:15:30Z","recoveredAmount":"example-recoveredamount","assignedTo":"example-assignedto","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","documents":[{"id":"00000000-0000-4000-8000-000000000001","documentType":"example-documenttype","title":"Example adr_request","source":"example-source","externalDocumentId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"ADR request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/adr/requests/{adrId}/submit":{"post":{"operationId":"submitAdrResponse","summary":"Mark ADR response submitted","description":"Marks an organization-scoped ADR response as submitted and stores the local submission method and optional tracking identifier.\n\n### When to use\nUse this after staff or automation has completed the supporting-document response process and QuickRCM should track that the ADR response was submitted.\n\n### Before calling\nLoad the ADR and confirm it is in a submittable local state: ADR_RECEIVED, ADR_IN_PROGRESS, or ADR_DOCS_ASSEMBLED. Write calls require adr:write scope.\n\n### Request guidance\nsubmissionMethod is required and must be one of the attachment submission method enum values. submissionTrackingId is optional and should be only a confirmation or reference identifier, not credentials, raw payloads, or signed URLs.\n\n### Request notes\n- Only ADR_RECEIVED, ADR_IN_PROGRESS, and ADR_DOCS_ASSEMBLED are submittable states.\n- Use adrId from the same organization context as the API key.\n- Do not use this as proof of external acceptance.\n\n### Response semantics\nThe response returns the updated local ADR record with status ADR_SUBMITTED, submittedAt populated by the server, submissionMethod set, and submissionTrackingId set or null. This endpoint records local submission tracking; it does not prove payer receipt or adjudication.\n\n### Response notes\n- The ADR status becomes ADR_SUBMITTED on success.\n- submittedAt is generated by the server.\n- submission fields remain local workflow metadata.\n\n### Errors and retries\nA 400 can mean missing submissionMethod or a non-submittable ADR status. After a timeout, re-read the ADR before retrying to avoid duplicate status-transition noise.\n\n### Error notes\n- 400 means the request shape or ADR status is invalid.\n- 404 means adrId is missing or wrong tenant.\n- 403 means the API key lacks adr:write scope.\n","tags":["ADR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"adrId","in":"path","description":"QuickRCM ADR identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"submissionMethod":{"type":"string","enum":["ATT_ELECTRONIC_275","ATT_PWK_LOOP","ATT_PAYER_PORTAL","ATT_FAX","ATT_MAIL","ATT_AVAILITY_ATTACHMENTS"],"description":"How the ADR response was submitted or tracked. Valid values include ATT_ELECTRONIC_275 for an X12 275-style electronic attachment workflow, ATT_PWK_LOOP for paperwork attachment-support tracking, ATT_PAYER_PORTAL, ATT_FAX, ATT_MAIL, and ATT_AVAILITY_ATTACHMENTS."},"submissionTrackingId":{"type":"string","minLength":1,"maxLength":160,"description":"Optional confirmation or tracking identifier for the local submission record. Do not store credentials or raw vendor payloads."}},"required":["submissionMethod"]},"example":{"submissionMethod":"ATT_ELECTRONIC_275","submissionTrackingId":"00000000-0000-4000-8000-000000000001"}}},"description":"submissionMethod is required and must be one of the attachment submission method enum values. submissionTrackingId is optional and should be only a confirmation or reference identifier, not credentials, raw payloads, or signed URLs."},"responses":{"200":{"description":"ADR request submitted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":"string"},"adrType":{"type":"string","enum":["ADR_PREPAYMENT_REVIEW","ADR_POST_PAYMENT_REVIEW","ADR_RAC_REQUEST","ADR_PAYER_CLINICAL_REVIEW","ADR_PRIOR_AUTH_SUPPORT","ADR_HOSPICE_AUDIT"]},"status":{"type":"string","enum":["ADR_RECEIVED","ADR_IN_PROGRESS","ADR_DOCS_ASSEMBLED","ADR_SUBMITTED","ADR_OUTCOME_APPROVED","ADR_OUTCOME_DENIED","ADR_OVERDUE","ADR_EXPIRED"]},"receivedDate":{"type":"string","format":"date-time"},"responseDeadline":{"type":"string","format":"date-time"},"isOverdue":{"type":"boolean"},"requestedDocTypes":{"type":"array","items":{"type":"string"}},"requestorName":{"type":["string","null"]},"requestorEntity":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"submissionMethod":{"type":["string","null"],"enum":["ATT_ELECTRONIC_275","ATT_PWK_LOOP","ATT_PAYER_PORTAL","ATT_FAX","ATT_MAIL","ATT_AVAILITY_ATTACHMENTS"]},"submissionTrackingId":{"type":["string","null"]},"outcomeDate":{"type":["string","null"],"format":"date-time"},"recoveredAmount":{"type":["string","null"]},"assignedTo":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","documentType","title","source","externalDocumentId","createdAt"]}}},"required":["id","organizationId","claimId","adrType","status","receivedDate","responseDeadline","isOverdue","requestedDocTypes","requestorName","requestorEntity","trackingNumber","submittedAt","submissionMethod","submissionTrackingId","outcomeDate","recoveredAmount","assignedTo","createdAt","updatedAt","documents"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","adrType":"ADR_PREPAYMENT_REVIEW","status":"ADR_RECEIVED","receivedDate":"2026-06-08T10:15:30Z","responseDeadline":"2026-06-08T10:15:30Z","isOverdue":true,"requestedDocTypes":["example-requesteddoctypes"],"requestorName":"Example adr_response","requestorEntity":"example-requestorentity","trackingNumber":"example-trackingnumber","submittedAt":"2026-06-08T10:15:30Z","submissionMethod":"ATT_ELECTRONIC_275","submissionTrackingId":"00000000-0000-4000-8000-000000000001","outcomeDate":"2026-06-08T10:15:30Z","recoveredAmount":"example-recoveredamount","assignedTo":"example-assignedto","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","documents":[{"id":"00000000-0000-4000-8000-000000000001","documentType":"example-documenttype","title":"Example adr_response","source":"example-source","externalDocumentId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"ADR request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/adr/requests/{adrId}/documents/assemble":{"post":{"operationId":"assembleAdrDocuments","summary":"Simulate ADR document assembly","description":"Validates an organization-scoped ADR and returns a simulated document assembly plan comparing requested document types with existing document references.\n\n### When to use\nUse this before document collection or automation to preview which requested document types still lack local ADR document references.\n\n### Before calling\nResolve adrId and confirm the API key has adr:write scope. This public endpoint only supports simulated validation.\n\n### Request guidance\nSend validateOnly true, or omit it and rely on the default true value. This public endpoint does not accept a mode that creates documents, uploads files, writes storage objects, or changes ADR status.\n\n### Request notes\n- validateOnly is always true for the public contract.\n- No file content should be sent in this request.\n- Use addAdrDocument when you need to register document-reference metadata.\n\n### Response semantics\nThe response always uses mode SIMULATED_ONLY and reports requestedDocumentTypes, existingDocumentTypes, and wouldAssembleDocumentTypes. sideEffects.createsClaimAttachmentDocuments and sideEffects.writesToStorage are both false.\n\n### Response notes\n- SIMULATED_ONLY means the endpoint did not create document records.\n- wouldAssembleDocumentTypes are requested document types with no matching existing reference.\n- writesToStorage is false.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization ADR context. 400 means the request body does not satisfy the validate-only schema. Retrying a successful simulation is safe because it has no write side effects.\n\n### Error notes\n- 404 means adrId is unavailable to this tenant.\n- 403 means the API key lacks adr:write scope.\n- 400 means validateOnly was not accepted by the public schema.\n","tags":["ADR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"adrId","in":"path","description":"QuickRCM Additional Documentation Request identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","enum":[true],"default":true,"description":"Must be true or omitted. The public endpoint is simulation-only."}}},"example":{"validateOnly":true}}},"description":"Send validateOnly true, or omit it and rely on the default true value. This public endpoint does not accept a mode that creates documents, uploads files, writes storage objects, or changes ADR status."},"responses":{"200":{"description":"Document assembly simulation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY"]},"status":{"type":"string","enum":["validated"]},"adrId":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":"string"},"requestedDocumentTypes":{"type":"array","items":{"type":"string"}},"existingDocumentTypes":{"type":"array","items":{"type":"string"}},"wouldAssembleDocumentTypes":{"type":"array","items":{"type":"string"}},"sideEffects":{"type":"object","properties":{"createsClaimAttachmentDocuments":{"type":"boolean","enum":[false]},"writesToStorage":{"type":"boolean","enum":[false]}},"required":["createsClaimAttachmentDocuments","writesToStorage"]}},"required":["mode","status","adrId","organizationId","claimId","requestedDocumentTypes","existingDocumentTypes","wouldAssembleDocumentTypes","sideEffects"]}},"required":["success","data"]},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","status":"validated","adrId":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","requestedDocumentTypes":["example-requesteddocumenttypes"],"existingDocumentTypes":["example-existingdocumenttypes"],"wouldAssembleDocumentTypes":["example-wouldassembledocumenttypes"],"sideEffects":{"createsClaimAttachmentDocuments":false,"writesToStorage":false}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"ADR request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/adr/requests/{adrId}/documents":{"post":{"operationId":"addAdrDocument","summary":"Add an ADR document reference","description":"Validates or registers an external document reference for an organization-scoped ADR.\n\n### When to use\nUse this when a supporting document already exists in an external system or local workflow and QuickRCM needs a document-reference record tied to the ADR and claim.\n\n### Before calling\nResolve adrId and confirm the document reference is appropriate for the claim and ADR. Write calls require adr:write scope.\n\n### Request guidance\nSend documentType, title, and source. validateOnly defaults to true and returns a dry-run preview. Set validateOnly to false only when you intentionally want QuickRCM to create a ClaimAttachmentDocument metadata row. externalDocumentId is optional and should be an opaque reference, not a signed URL or credential.\n\n### Request notes\n- documentType, title, and source are required.\n- validateOnly true is the safe default and creates no record.\n- validateOnly false creates metadata only; it does not upload a file.\n\n### Response semantics\nWith validateOnly true, the response is 200 with mode SIMULATED_ONLY and wouldCreateDocument. With validateOnly false, the response is 201 with mode SAFE_WRITE_DB_ONLY and a created document metadata record. In both cases, writesToStorage is false and no file contents are uploaded.\n\n### Response notes\n- SIMULATED_ONLY responses preview the document reference.\n- SAFE_WRITE_DB_ONLY responses create a ClaimAttachmentDocument metadata row with s3Key null.\n- externalDocumentId is returned only when stored in document metadata.\n\n### Errors and retries\nAfter a timeout with validateOnly false, inspect the ADR documents before retrying to avoid duplicate references. Fix 400 validation errors and 404 wrong-tenant ADR references before retrying.\n\n### Error notes\n- 400 means document metadata is invalid.\n- 404 means adrId is unavailable to this tenant.\n- 403 means the API key lacks adr:write scope.\n","tags":["ADR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"adrId","in":"path","description":"QuickRCM ADR identifier in the path. It must resolve inside the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"documentType":{"type":"string","minLength":1,"maxLength":100,"description":"Supporting document category attached to the ADR, such as clinical_notes or operative_report in local workflows."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Human-readable document title. Avoid embedding PHI beyond what the ADR workflow requires."},"source":{"type":"string","minLength":1,"maxLength":80,"description":"Short source label for the document reference, such as external_reference or manual. Do not put credentials or URLs here."},"externalDocumentId":{"type":"string","minLength":1,"maxLength":160,"description":"Optional opaque identifier from an external document system. Do not use signed URLs, S3 keys, or credentials."},"validateOnly":{"type":"boolean","default":true,"description":"When true or omitted, validates and previews the reference without creating a row. When false, creates metadata only."}},"required":["documentType","title","source"]},"example":{"documentType":"example-documenttype","title":"Example add_adr_document","source":"example-source","externalDocumentId":"00000000-0000-4000-8000-000000000001","validateOnly":true}}},"description":"Send documentType, title, and source. validateOnly defaults to true and returns a dry-run preview. Set validateOnly to false only when you intentionally want QuickRCM to create a ClaimAttachmentDocument metadata row. externalDocumentId is optional and should be an opaque reference, not a signed URL or credential."},"responses":{"200":{"description":"Document add simulation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY"]},"status":{"type":"string","enum":["validated"]},"wouldCreateDocument":{"type":"object","properties":{"organizationId":{"type":"string"},"adrId":{"type":"string"},"claimId":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]}},"required":["organizationId","adrId","claimId","documentType","title","source","externalDocumentId"]},"sideEffects":{"type":"object","properties":{"createsClaimAttachmentDocument":{"type":"boolean","enum":[false]},"writesToStorage":{"type":"boolean","enum":[false]}},"required":["createsClaimAttachmentDocument","writesToStorage"]}},"required":["mode","status","wouldCreateDocument","sideEffects"]},{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"status":{"type":"string","enum":["created"]},"document":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","documentType","title","source","externalDocumentId","createdAt"]},"sideEffects":{"type":"object","properties":{"createsClaimAttachmentDocument":{"type":"boolean","enum":[true]},"writesToStorage":{"type":"boolean","enum":[false]}},"required":["createsClaimAttachmentDocument","writesToStorage"]}},"required":["mode","status","document","sideEffects"]}]}},"required":["success","data"]},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","status":"validated","wouldCreateDocument":{"organizationId":"00000000-0000-4000-8000-000000000001","adrId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","documentType":"example-documenttype","title":"Example add_adr_document","source":"example-source","externalDocumentId":"00000000-0000-4000-8000-000000000001"},"sideEffects":{"createsClaimAttachmentDocument":false,"writesToStorage":false}}}}}},"201":{"description":"Document reference registered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY"]},"status":{"type":"string","enum":["validated"]},"wouldCreateDocument":{"type":"object","properties":{"organizationId":{"type":"string"},"adrId":{"type":"string"},"claimId":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]}},"required":["organizationId","adrId","claimId","documentType","title","source","externalDocumentId"]},"sideEffects":{"type":"object","properties":{"createsClaimAttachmentDocument":{"type":"boolean","enum":[false]},"writesToStorage":{"type":"boolean","enum":[false]}},"required":["createsClaimAttachmentDocument","writesToStorage"]}},"required":["mode","status","wouldCreateDocument","sideEffects"]},{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"status":{"type":"string","enum":["created"]},"document":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","documentType","title","source","externalDocumentId","createdAt"]},"sideEffects":{"type":"object","properties":{"createsClaimAttachmentDocument":{"type":"boolean","enum":[true]},"writesToStorage":{"type":"boolean","enum":[false]}},"required":["createsClaimAttachmentDocument","writesToStorage"]}},"required":["mode","status","document","sideEffects"]}]}},"required":["success","data"]},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","status":"validated","wouldCreateDocument":{"organizationId":"00000000-0000-4000-8000-000000000001","adrId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","documentType":"example-documenttype","title":"Example add_adr_document","source":"example-source","externalDocumentId":"00000000-0000-4000-8000-000000000001"},"sideEffects":{"createsClaimAttachmentDocument":false,"writesToStorage":false}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"ADR request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/adr/requests/{adrId}/outcome":{"put":{"operationId":"recordAdrOutcome","summary":"Record ADR outcome","description":"Records an approved or denied outcome for an organization-scoped ADR that is already in ADR_SUBMITTED status.\n\n### When to use\nUse this when the reviewer, payer, CMS contractor, RAC, or internal workflow has a final ADR outcome and QuickRCM should update local tracking and recovery reporting.\n\n### Before calling\nLoad the ADR and confirm it has status ADR_SUBMITTED. Write calls require adr:write scope. Capture only outcome facts that are known and supportable.\n\n### Request guidance\noutcome is required and must be ADR_OUTCOME_APPROVED or ADR_OUTCOME_DENIED. outcomeNotes is optional and capped at 2,000 characters. recoveredAmount is optional, non-negative, and should be supplied only for confirmed approved recoveries.\n\n### Request notes\n- Only ADR_SUBMITTED records can receive an outcome.\n- Keep outcomeNotes concise and free of raw payer payloads, raw EDI, credentials, or unnecessary PHI.\n- Use recoveredAmount only when it is confirmed and non-negative.\n\n### Response semantics\nThe response uses mode SAFE_WRITE_DB_ONLY and returns the updated ADR. Approved outcomes can retain recoveredAmount, including explicit zero. Denied outcomes store recoveredAmount as null in the public handler.\n\n### Response notes\n- status becomes ADR_OUTCOME_APPROVED or ADR_OUTCOME_DENIED.\n- mode SAFE_WRITE_DB_ONLY means the endpoint updates local ADR state only.\n- recoveredAmount is serialized as a string or null in ADR responses.\n\n### Errors and retries\nA 400 can mean invalid outcome, invalid amount, or attempting to record an outcome before ADR_SUBMITTED. Re-read the ADR after a timeout before retrying to avoid duplicate outcome note changes.\n\n### Error notes\n- 400 means invalid outcome data or invalid ADR status.\n- 404 means adrId is unavailable to this tenant.\n- 403 means the API key lacks adr:write scope.\n","tags":["ADR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"adrId","in":"path","description":"QuickRCM ADR identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["ADR_OUTCOME_APPROVED","ADR_OUTCOME_DENIED"],"description":"Final ADR outcome enum. Use ADR_OUTCOME_APPROVED or ADR_OUTCOME_DENIED."},"outcomeNotes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional staff-readable notes explaining the outcome. Avoid raw payloads, credentials, or unnecessary PHI."},"recoveredAmount":{"type":["number","null"],"minimum":0,"description":"Optional non-negative amount recovered for an approved ADR outcome. Denied outcomes store recoveredAmount as null."}},"required":["outcome"]},"example":{"outcome":"ADR_OUTCOME_APPROVED","outcomeNotes":"Example adr_outcome note","recoveredAmount":125.5}}},"description":"outcome is required and must be ADR_OUTCOME_APPROVED or ADR_OUTCOME_DENIED. outcomeNotes is optional and capped at 2,000 characters. recoveredAmount is optional, non-negative, and should be supplied only for confirmed approved recoveries."},"responses":{"200":{"description":"ADR outcome recorded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"adr":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":"string"},"adrType":{"type":"string","enum":["ADR_PREPAYMENT_REVIEW","ADR_POST_PAYMENT_REVIEW","ADR_RAC_REQUEST","ADR_PAYER_CLINICAL_REVIEW","ADR_PRIOR_AUTH_SUPPORT","ADR_HOSPICE_AUDIT"]},"status":{"type":"string","enum":["ADR_RECEIVED","ADR_IN_PROGRESS","ADR_DOCS_ASSEMBLED","ADR_SUBMITTED","ADR_OUTCOME_APPROVED","ADR_OUTCOME_DENIED","ADR_OVERDUE","ADR_EXPIRED"]},"receivedDate":{"type":"string","format":"date-time"},"responseDeadline":{"type":"string","format":"date-time"},"isOverdue":{"type":"boolean"},"requestedDocTypes":{"type":"array","items":{"type":"string"}},"requestorName":{"type":["string","null"]},"requestorEntity":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"submissionMethod":{"type":["string","null"],"enum":["ATT_ELECTRONIC_275","ATT_PWK_LOOP","ATT_PAYER_PORTAL","ATT_FAX","ATT_MAIL","ATT_AVAILITY_ATTACHMENTS"]},"submissionTrackingId":{"type":["string","null"]},"outcomeDate":{"type":["string","null"],"format":"date-time"},"recoveredAmount":{"type":["string","null"]},"assignedTo":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":"string"},"title":{"type":"string"},"source":{"type":"string"},"externalDocumentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","documentType","title","source","externalDocumentId","createdAt"]}}},"required":["id","organizationId","claimId","adrType","status","receivedDate","responseDeadline","isOverdue","requestedDocTypes","requestorName","requestorEntity","trackingNumber","submittedAt","submissionMethod","submissionTrackingId","outcomeDate","recoveredAmount","assignedTo","createdAt","updatedAt","documents"]}},"required":["mode","adr"]}},"required":["success","data"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","adr":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","adrType":"ADR_PREPAYMENT_REVIEW","status":"ADR_RECEIVED","receivedDate":"2026-06-08T10:15:30Z","responseDeadline":"2026-06-08T10:15:30Z","isOverdue":true,"requestedDocTypes":["example-requesteddoctypes"],"requestorName":"Example adr_outcome","requestorEntity":"example-requestorentity","trackingNumber":"example-trackingnumber","submittedAt":"2026-06-08T10:15:30Z","submissionMethod":"ATT_ELECTRONIC_275","submissionTrackingId":"00000000-0000-4000-8000-000000000001","outcomeDate":"2026-06-08T10:15:30Z","recoveredAmount":"example-recoveredamount","assignedTo":"example-assignedto","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","documents":[{"id":"00000000-0000-4000-8000-000000000001","documentType":"example-documenttype","title":"Example adr_outcome","source":"example-source","externalDocumentId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z"}]}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"ADR request not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/definitions":{"get":{"operationId":"listAgentBuilderDefinitions","summary":"List agent definitions","description":"Returns paginated, organization-scoped metadata for Agent Builder definitions, filtered by lifecycle status, RCM category, application type, or search text.\n\n### When to use\nUse this before showing an integration-facing catalog of definitions or before choosing a definition for schedules, executions, cloning, publishing, or updates.\n\n### Before calling\nAuthenticate with Agent Builder read access and apply narrow filters when the tenant has many definitions.\n\n### Request guidance\nUse `limit` and `offset` for pagination. Use `search` only for non-PHI metadata such as definition names or application names.\n\n### Request notes\n- Use `limit` and `offset` on every production list request.\n- Filter by `status`, `category`, `applicationType`, or non-PHI `search` text to avoid broad catalog scans.\n\n### Response semantics\nA 200 response returns `SAFE_READ_DB_ONLY` definition metadata and pagination details; raw `steps`, extraction schemas, transformation maps, credentials, and schedule secrets are not returned.\n\n### Response notes\n- `data.mode` is `SAFE_READ_DB_ONLY`.\n- Definition list responses include metadata only and do not include raw steps, schemas, transformation maps, or credential links.\n\n### Errors and retries\nRetry 429 responses after backing off. Treat 403 as missing Agent Builder read permission for the authenticated organization.\n\n### Error notes\n- 400 means query filters failed schema validation.\n- 403 means the API key or mapped user lacks Agent Builder read access.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query","description":"Maximum page size, 1 to 100; defaults to 50."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query","description":"Zero-based row offset for pagination; defaults to 0."},{"schema":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"required":false,"name":"status","in":"query","description":"Optional lifecycle filter for definitions: `DRAFT`, `ACTIVE`, `PAUSED`, or `ARCHIVED`."},{"schema":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"required":false,"name":"category","in":"query","description":"Optional Agent Builder RCM category filter."},{"schema":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"required":false,"name":"applicationType","in":"query","description":"Optional target application class filter."},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"search","in":"query","description":"Optional 1-200 character metadata search string."}],"responses":{"200":{"description":"Agent definitions for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"agentDefinitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"applicationUrl":{"type":"string"},"applicationName":{"type":"string"},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"version":{"type":"integer"},"requiresApproval":{"type":"boolean"},"creditCost":{"type":"integer"},"tokenBudget":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"maxRetries":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","slug","description","category","applicationUrl","applicationName","applicationType","mode","status","version","requiresApproval","creditCost","tokenBudget","timeoutSeconds","maxRetries","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"]}},"required":["mode","agentDefinitions","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","agentDefinitions":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_definition","slug":"example-slug","description":"Example agent_builder_definition note","category":"ELIGIBILITY","applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example agent_builder_definition","applicationType":"EHR","mode":"READ","status":"DRAFT","version":1,"requiresApproval":true,"creditCost":1,"tokenBudget":1,"timeoutSeconds":1,"maxRetries":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"pagination":{"limit":1,"offset":1,"total":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createAgentBuilderDefinition","summary":"Create agent definition","description":"Creates a new Agent Builder definition as an organization-scoped database-only write and returns safe definition metadata.\n\n### When to use\nUse this when an external implementation tool is ready to register a visual RPA workflow definition before schedules or executions are created.\n\n### Before calling\nPrepare a non-PHI agent name, target application metadata, and at least one step. If using `defaultCredentialId`, resolve it from the same organization first.\n\n### Request guidance\nSend structured step definitions and extraction/transformation configuration only. Keep portal credentials out of `description`, `tags`, `steps`, and `inputVariables`; reference credentials by ID instead.\n\n### Request notes\n- `steps` must contain 1 to 200 step objects with supported `type` values and non-empty `instruction` strings.\n- `description` is optional and capped at 5000 characters; `icon` is optional and capped at 100 characters.\n- `tags` accepts up to 50 non-empty strings, each up to 100 characters.\n- Default create values include `category: CUSTOM`, `applicationType: CUSTOM`, `mode: READ`, `requiresApproval: false`, `creditCost: 5`, `tokenBudget: 30000`, `timeoutSeconds: 300`, and `maxRetries: 3`.\n\n### Response semantics\nA 201 response creates a `DRAFT` definition and returns `SAFE_WRITE_DB_ONLY` metadata. It does not run the agent and does not return the submitted step body.\n\n### Response notes\n- `data.mode` is `SAFE_WRITE_DB_ONLY`.\n- The response includes the generated `slug`, lifecycle `status`, and runtime-control metadata, but not the raw step list.\n\n### Errors and retries\nFix 400 validation failures before retrying. A 409 means the generated slug conflicts with an existing definition name in the organization. After a timeout, list definitions before creating another copy.\n\n### Error notes\n- 400 can indicate an invalid credential reference, inactive or locked credential, malformed step, or validation range failure.\n- 409 means the name-derived slug is already used by another definition in the authenticated organization.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Required human-readable definition name, 1-200 characters; used to generate a tenant-scoped slug."},"description":{"type":"string","maxLength":5000,"description":"Optional definition description, up to 5000 characters. Keep it operational and free of PHI or secrets."},"icon":{"type":"string","maxLength":100,"description":"Optional short icon identifier or display token, up to 100 characters."},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"],"default":"CUSTOM","description":"Optional RCM category; defaults to `CUSTOM`."},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"default":[],"description":"Optional metadata labels, up to 50 entries, for filtering and UI grouping."},"applicationUrl":{"type":"string","minLength":1,"maxLength":2048,"description":"Required target portal or application URL, up to 2048 characters. Do not include session tokens or signed URLs."},"applicationName":{"type":"string","minLength":1,"maxLength":200,"description":"Required display name of the target application or portal, up to 200 characters."},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"],"default":"CUSTOM","description":"Optional target application class; defaults to `CUSTOM`."},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"],"default":"READ","description":"Optional execution intent: `READ`, `WRITE`, or `READ_WRITE`; defaults to `READ`."},"steps":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["NAVIGATE","ACT","EXTRACT","OBSERVE","WAIT","CONDITION","LOOP","APPROVAL_GATE","SUB_AGENT"],"description":"Supported step vocabulary: `NAVIGATE`, `ACT`, `EXTRACT`, `OBSERVE`, `WAIT`, `CONDITION`, `LOOP`, `APPROVAL_GATE`, or `SUB_AGENT`."},"instruction":{"type":"string","minLength":1,"maxLength":4000,"description":"Required natural-language instruction for the step, 1-4000 characters. Avoid PHI, credentials, and raw portal payloads."}},"required":["type","instruction"]},"minItems":1,"maxItems":200,"description":"Required ordered visual RPA step definitions. Treat as sensitive automation source."},"extractionSchema":{"type":"object","additionalProperties":{},"description":"Optional JSON object describing extracted fields; keep it narrow and PHI-minimal."},"transformationMap":{"type":"object","additionalProperties":{},"description":"Optional JSON object for mapping extracted values into QuickRCM structures."},"inputVariables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Required runtime variable name, 1-100 characters."},"type":{"type":"string","enum":["string","number","boolean","date","select"],"description":"Optional runtime variable type: `string`, `number`, `boolean`, `date`, or `select`."},"required":{"type":"boolean","description":"Optional boolean that marks whether execution callers must supply the variable."}},"required":["name"]},"maxItems":100,"description":"Optional declared runtime variables used by step instructions, up to 100 entries."},"defaultCredentialId":{"type":"string","minLength":1,"description":"Optional automation credential ID owned by the same organization; credential secrets are never sent in this request."},"requiresApproval":{"type":"boolean","default":false,"description":"Optional boolean approval gate for write-capable or sensitive workflow definitions; defaults to false."},"creditCost":{"type":"integer","minimum":0,"maximum":10000,"default":5,"description":"Optional configured credit cost, 0-10000; defaults to 5."},"tokenBudget":{"type":"integer","minimum":1000,"maximum":500000,"default":30000,"description":"Optional maximum LLM token budget, 1000-500000; defaults to 30000."},"timeoutSeconds":{"type":"integer","minimum":30,"maximum":7200,"default":300,"description":"Optional maximum execution duration, 30-7200 seconds; defaults to 300."},"maxRetries":{"type":"integer","minimum":0,"maximum":10,"default":3,"description":"Optional maximum retry count, 0-10; defaults to 3."}},"required":["name","applicationUrl","applicationName","steps"]},"example":{"name":"Example agent_builder_definition","applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example agent_builder_definition","steps":[{"type":"NAVIGATE","instruction":"example-instruction"}],"description":"Example agent_builder_definition note","icon":"example-icon","category":"CUSTOM","tags":[],"applicationType":"CUSTOM","mode":"READ","extractionSchema":{},"transformationMap":{}}}},"description":"Send structured step definitions and extraction/transformation configuration only. Keep portal credentials out of `description`, `tags`, `steps`, and `inputVariables`; reference credentials by ID instead."},"responses":{"201":{"description":"Agent definition created for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"agentDefinition":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"applicationUrl":{"type":"string"},"applicationName":{"type":"string"},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"version":{"type":"integer"},"requiresApproval":{"type":"boolean"},"creditCost":{"type":"integer"},"tokenBudget":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"maxRetries":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","slug","description","category","applicationUrl","applicationName","applicationType","mode","status","version","requiresApproval","creditCost","tokenBudget","timeoutSeconds","maxRetries","createdAt","updatedAt"]}},"required":["mode","agentDefinition"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","agentDefinition":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_definition","slug":"example-slug","description":"Example agent_builder_definition note","category":"ELIGIBILITY","applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example agent_builder_definition","applicationType":"EHR","mode":"READ","status":"DRAFT","version":1,"requiresApproval":true,"creditCost":1,"tokenBudget":1,"timeoutSeconds":1,"maxRetries":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/definitions/{agentId}":{"put":{"operationId":"updateAgentBuilderDefinition","summary":"Update agent definition","description":"Updates an existing organization-owned Agent Builder definition after an organization-scoped lookup and returns safe metadata.\n\n### When to use\nUse this to revise definition metadata, step instructions, extraction configuration, runtime limits, approval settings, or lifecycle status.\n\n### Before calling\nFetch or otherwise know the current `agentId`, decide whether the update changes executable behavior, and confirm any replacement credential belongs to the same organization.\n\n### Request guidance\nSend only intended replacement fields. Nullable fields can clear optional metadata where the schema allows null. Avoid embedding payer portal credentials, patient identifiers, or raw browser output in updated step instructions.\n\n### Request notes\n- `description`, `icon`, `extractionSchema`, `transformationMap`, `inputVariables`, and `defaultCredentialId` may be nullable according to the update schema.\n- Changing `steps` or extraction configuration changes executable workflow behavior and should be reviewed before activating write-capable agents.\n- `maxRetries` remains constrained to 0-10, `tokenBudget` to 1000-500000, and `timeoutSeconds` to 30-7200.\n\n### Response semantics\nA 200 response confirms a database-only update and returns `SAFE_WRITE_DB_ONLY` definition metadata without returning the full step body.\n\n### Response notes\n- Response metadata remains sanitized and excludes submitted configuration bodies that may contain sensitive workflow details.\n- `status` can reflect lifecycle transitions such as `DRAFT`, `ACTIVE`, `PAUSED`, or `ARCHIVED` when accepted by the API.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization `agentId`, 409 as a slug conflict after renaming, and timeout retries as potentially overwriting concurrent edits unless the current definition is re-read.\n\n### Error notes\n- 400 can indicate invalid body fields or an inactive/locked credential reference.\n- 409 indicates the requested name would collide with another definition slug.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"path","description":"Path ID of the definition to update; it must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Optional replacement definition name, 1-200 characters; changing it can change the slug and cause conflicts."},"description":{"type":["string","null"],"maxLength":5000,"description":"Optional replacement description or null to clear it; up to 5000 characters."},"icon":{"type":["string","null"],"maxLength":100,"description":"Optional replacement icon identifier or null to clear it; up to 100 characters."},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"],"description":"Optional replacement RCM category."},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"description":"Optional replacement tag list, up to 50 entries."},"applicationUrl":{"type":"string","minLength":1,"maxLength":2048,"description":"Optional replacement target URL, up to 2048 characters; do not include tokens or signed URLs."},"applicationName":{"type":"string","minLength":1,"maxLength":200,"description":"Optional replacement target application display name, up to 200 characters."},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"],"description":"Optional replacement target application class."},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"],"description":"Optional replacement execution intent: `READ`, `WRITE`, or `READ_WRITE`."},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"],"description":"Optional lifecycle target for the definition: `DRAFT`, `ACTIVE`, `PAUSED`, or `ARCHIVED`."},"steps":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["NAVIGATE","ACT","EXTRACT","OBSERVE","WAIT","CONDITION","LOOP","APPROVAL_GATE","SUB_AGENT"],"description":"Required when a step is supplied; uses the supported Agent Builder step vocabulary."},"instruction":{"type":"string","minLength":1,"maxLength":4000,"description":"Required when a step is supplied; 1-4000 character operational instruction."}},"required":["type","instruction"]},"minItems":1,"maxItems":200,"description":"Optional replacement ordered step list, 1-200 entries."},"extractionSchema":{"type":["object","null"],"additionalProperties":{},"description":"Optional replacement extraction schema or null to clear it."},"transformationMap":{"type":["object","null"],"additionalProperties":{},"description":"Optional replacement transformation map or null to clear it."},"inputVariables":{"type":["array","null"],"items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["string","number","boolean","date","select"]},"required":{"type":"boolean"}},"required":["name"]},"maxItems":100,"description":"Optional replacement runtime variable list or null to clear it."},"defaultCredentialId":{"type":["string","null"],"minLength":1,"description":"Optional replacement default credential ID; null clears the link when accepted by the schema."},"requiresApproval":{"type":"boolean","description":"Optional approval requirement toggle for the definition."},"creditCost":{"type":"integer","minimum":0,"maximum":10000,"description":"Optional replacement credit cost, 0-10000."},"tokenBudget":{"type":"integer","minimum":1000,"maximum":500000,"description":"Optional replacement token budget, 1000-500000."},"timeoutSeconds":{"type":"integer","minimum":30,"maximum":7200,"description":"Optional replacement timeout, 30-7200 seconds."},"maxRetries":{"type":"integer","minimum":0,"maximum":10,"description":"Optional replacement retry count, 0-10."}}},"example":{"name":"Example agent_builder_definition","description":"Example agent_builder_definition note","icon":"example-icon","category":"ELIGIBILITY","tags":["example-tags"],"applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example agent_builder_definition","applicationType":"EHR"}}},"description":"Send only intended replacement fields. Nullable fields can clear optional metadata where the schema allows null. Avoid embedding payer portal credentials, patient identifiers, or raw browser output in updated step instructions."},"responses":{"200":{"description":"Agent definition updated for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"agentDefinition":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"applicationUrl":{"type":"string"},"applicationName":{"type":"string"},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"version":{"type":"integer"},"requiresApproval":{"type":"boolean"},"creditCost":{"type":"integer"},"tokenBudget":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"maxRetries":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","slug","description","category","applicationUrl","applicationName","applicationType","mode","status","version","requiresApproval","creditCost","tokenBudget","timeoutSeconds","maxRetries","createdAt","updatedAt"]}},"required":["mode","agentDefinition"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","agentDefinition":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_definition","slug":"example-slug","description":"Example agent_builder_definition note","category":"ELIGIBILITY","applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example agent_builder_definition","applicationType":"EHR","mode":"READ","status":"DRAFT","version":1,"requiresApproval":true,"creditCost":1,"tokenBudget":1,"timeoutSeconds":1,"maxRetries":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"get":{"operationId":"getAgentBuilderDefinition","summary":"Get agent definition","description":"Retrieves safe metadata for one Agent Builder definition in the authenticated organization.\n\n### When to use\nUse this to confirm definition metadata before updating, scheduling, cloning, publishing, or creating executions.\n\n### Before calling\nUse an `agentId` returned by a trusted Agent Builder response for the same tenant context.\n\n### Request guidance\nPass the path ID only; no request body is accepted.\n\n### Request notes\n- Use an `agentId` returned by the same tenant context.\n- No request body is accepted.\n\n### Response semantics\nA 200 response returns `SAFE_READ_DB_ONLY` metadata and omits raw step bodies, extraction schemas, transformation maps, and credential secrets.\n\n### Response notes\n- `data.mode` is `SAFE_READ_DB_ONLY`.\n- The response omits executable step bodies and credential secrets.\n\n### Errors and retries\nA 404 means the definition does not exist or is outside the authenticated organization.\n\n### Error notes\n- 404 can mean the definition is missing or outside the authenticated organization.\n- Retry 429 only after rate-limit backoff.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"path","description":"Path ID for the organization-owned Agent Builder definition."}],"responses":{"200":{"description":"Agent definition for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"agentDefinition":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"applicationUrl":{"type":"string"},"applicationName":{"type":"string"},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"version":{"type":"integer"},"requiresApproval":{"type":"boolean"},"creditCost":{"type":"integer"},"tokenBudget":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"maxRetries":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","slug","description","category","applicationUrl","applicationName","applicationType","mode","status","version","requiresApproval","creditCost","tokenBudget","timeoutSeconds","maxRetries","createdAt","updatedAt"]}},"required":["mode","agentDefinition"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","agentDefinition":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_definition","slug":"example-slug","description":"Example agent_builder_definition note","category":"ELIGIBILITY","applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example agent_builder_definition","applicationType":"EHR","mode":"READ","status":"DRAFT","version":1,"requiresApproval":true,"creditCost":1,"tokenBudget":1,"timeoutSeconds":1,"maxRetries":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"delete":{"operationId":"archiveAgentBuilderDefinition","summary":"Archive agent definition","description":"Archives an organization-owned Agent Builder definition through the DELETE endpoint and returns safe definition metadata.\n\n### When to use\nUse this when a definition should no longer be selected for new schedules or external workflow use.\n\n### Before calling\nConfirm downstream schedules, templates, or integrations no longer depend on the definition.\n\n### Request guidance\nPass the path ID only; no request body is accepted.\n\n### Request notes\n- Use a path `agentId` from a trusted Agent Builder response.\n- Review dependent schedules before archiving because the handler disables schedules for the definition.\n\n### Response semantics\nA 200 response returns `SAFE_WRITE_DB_ONLY` metadata for the archived definition.\n\n### Response notes\n- `data.mode` is `SAFE_WRITE_DB_ONLY`.\n- The returned definition metadata reflects the archived lifecycle state when the mutation succeeds.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization `agentId`; retry 429 only after rate-limit backoff.\n\n### Error notes\n- 404 can mean the definition is missing or outside the authenticated organization.\n- 403 means the caller lacks the required automation admin write permission.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"path","description":"Path ID for the organization-owned definition to archive."}],"responses":{"200":{"description":"Agent definition archived for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"agentDefinition":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"applicationUrl":{"type":"string"},"applicationName":{"type":"string"},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"version":{"type":"integer"},"requiresApproval":{"type":"boolean"},"creditCost":{"type":"integer"},"tokenBudget":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"maxRetries":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","slug","description","category","applicationUrl","applicationName","applicationType","mode","status","version","requiresApproval","creditCost","tokenBudget","timeoutSeconds","maxRetries","createdAt","updatedAt"]}},"required":["mode","agentDefinition"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","agentDefinition":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example archive_agent_builder_definition","slug":"example-slug","description":"Example archive_agent_builder_definition note","category":"ELIGIBILITY","applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example archive_agent_builder_definition","applicationType":"EHR","mode":"READ","status":"DRAFT","version":1,"requiresApproval":true,"creditCost":1,"tokenBudget":1,"timeoutSeconds":1,"maxRetries":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/definitions/{agentId}/clone":{"post":{"operationId":"cloneAgentBuilderDefinition","summary":"Clone agent definition","description":"Clones an organization-owned Agent Builder definition into a new draft definition and returns safe metadata for the clone.\n\n### When to use\nUse this to create a tenant-local copy before experimenting with metadata, steps, credentials, or runtime controls.\n\n### Before calling\nFetch the source definition metadata and choose an optional non-PHI replacement name when the default clone naming is not desired.\n\n### Request guidance\nOnly `name` is accepted in the request body; do not include step or credential payloads.\n\n### Request notes\n- Only `name` is accepted in the body and it is optional.\n- If `name` is omitted, the clone name is derived from the source definition.\n\n### Response semantics\nA 201 response returns `SAFE_WRITE_DB_ONLY` metadata for the cloned draft and does not expose raw step bodies.\n\n### Response notes\n- `data.mode` is `SAFE_WRITE_DB_ONLY`.\n- The clone is returned as a draft definition metadata record without raw step bodies.\n\n### Errors and retries\nA 409 can indicate a name-derived slug conflict for the clone.\n\n### Error notes\n- 409 can mean the requested clone name cannot produce a unique slug.\n- 404 can mean the source definition is missing or outside the authenticated organization.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"path","description":"Path ID for the source definition to clone."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Optional replacement name for the cloned definition."}}},"example":{"name":"Example clone_agent_builder_definition"}}},"description":"Only `name` is accepted in the request body; do not include step or credential payloads."},"responses":{"201":{"description":"Agent definition cloned for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"agentDefinition":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"applicationUrl":{"type":"string"},"applicationName":{"type":"string"},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"version":{"type":"integer"},"requiresApproval":{"type":"boolean"},"creditCost":{"type":"integer"},"tokenBudget":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"maxRetries":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","slug","description","category","applicationUrl","applicationName","applicationType","mode","status","version","requiresApproval","creditCost","tokenBudget","timeoutSeconds","maxRetries","createdAt","updatedAt"]}},"required":["mode","agentDefinition"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","agentDefinition":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example clone_agent_builder_definition","slug":"example-slug","description":"Example clone_agent_builder_definition note","category":"ELIGIBILITY","applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example clone_agent_builder_definition","applicationType":"EHR","mode":"READ","status":"DRAFT","version":1,"requiresApproval":true,"creditCost":1,"tokenBudget":1,"timeoutSeconds":1,"maxRetries":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/schedules":{"get":{"operationId":"listAgentBuilderSchedules","summary":"List agent schedules","description":"Returns paginated, organization-scoped schedule metadata for Agent Builder schedules.\n\n### When to use\nUse this to inspect schedule state before pause, resume, update, delete, or operational monitoring workflows.\n\n### Before calling\nDecide whether to filter by a specific `agentDefinitionId`, trigger type, or active state.\n\n### Request guidance\nUse pagination and filters instead of retrieving every schedule. No schedule input parameters, alert recipients, credentials, or webhook secrets are returned.\n\n### Request notes\n- Use `agentDefinitionId`, `triggerType`, or `isActive` filters when reconciling schedules.\n- Use pagination instead of scanning every schedule in the tenant.\n\n### Response semantics\nA 200 response returns `SAFE_READ_DB_ONLY` schedule metadata and pagination.\n\n### Response notes\n- `data.mode` is `SAFE_READ_DB_ONLY`.\n- Schedule list responses omit webhook secrets, runtime input parameters, credentials, alerts, and blackout details.\n\n### Errors and retries\nA 403 indicates missing Agent Builder schedule read permission; retry 429 after backoff.\n\n### Error notes\n- 400 means a query parameter failed schema validation.\n- 403 means the caller lacks Agent Builder read access.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query","description":"Maximum page size, 1 to 100; defaults to 50."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query","description":"Zero-based row offset for pagination; defaults to 0."},{"schema":{"type":"string","minLength":1},"required":false,"name":"agentDefinitionId","in":"query","description":"Optional filter for schedules attached to one Agent Builder definition."},{"schema":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"]},"required":false,"name":"triggerType","in":"query","description":"Optional schedule trigger filter."},{"schema":{"type":"boolean"},"required":false,"name":"isActive","in":"query","description":"Optional boolean filter for active or inactive schedules."}],"responses":{"200":{"description":"Agent schedules for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"name":{"type":["string","null"]},"triggerType":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"]},"cronExpression":{"type":["string","null"]},"intervalMinutes":{"type":["integer","null"]},"timezone":{"type":"string"},"isActive":{"type":"boolean"},"nextRunAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","name","triggerType","cronExpression","intervalMinutes","timezone","isActive","nextRunAt","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"]}},"required":["mode","schedules","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","schedules":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_schedule","triggerType":"CRON","cronExpression":"example-cronexpression","intervalMinutes":1,"timezone":"example-timezone","isActive":true,"nextRunAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"pagination":{"limit":1,"offset":1,"total":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/definitions/{agentId}/schedules":{"post":{"operationId":"createAgentBuilderSchedule","summary":"Create agent schedule","description":"Creates an organization-scoped schedule under a non-archived Agent Builder definition.\n\n### When to use\nUse this when an agent definition should be run later by cron, interval, event, webhook, manual, or dependency-triggered scheduling.\n\n### Before calling\nConfirm the `agentId` belongs to the organization and is not archived. Resolve credential and dependency schedule IDs from the same organization.\n\n### Request guidance\n`CRON` schedules require `cronExpression`; `INTERVAL` schedules require `intervalMinutes`. Avoid placing PHI, secrets, raw payer payloads, or portal credentials in `inputParams`, `webhookSecret`, or alert fields.\n\n### Request notes\n- `name` is optional and capped at 200 characters when provided.\n- `timezone` defaults to `America/New_York` when omitted.\n- `maxConcurrentRuns` defaults to 1 and is constrained to 1-50.\n- `retryOnFailure` defaults to true, `maxRetries` defaults to 3, `priority` defaults to `NORMAL`, `alertOnFailure` defaults to true, `alertEmails` defaults to an empty list, `pauseAfterFailures` defaults to 3, and `isActive` defaults to true.\n- Create/update schedule can accept a caller-provided `webhookSecret`, but create/update responses do not return it; use the rotate endpoint to generate and display a new secret once.\n\n### Response semantics\nA 201 response creates schedule metadata and returns `SAFE_WRITE_DB_ONLY`. The response omits `webhookSecret`, `inputParams`, credential linkage, retry settings, alert emails, and blackout details.\n\n### Response notes\n- `nextRunAt` is computed for CRON schedules when the API can calculate it.\n- Schedule creation does not itself create an execution.\n\n### Errors and retries\nFix validation errors before retrying. A 400 can indicate an archived agent, missing trigger-specific field, invalid cron expression, bad credential, or missing dependency schedule.\n\n### Error notes\n- 404 means the agent definition was not found in the authenticated organization.\n- 400 can mean the referenced credential is inactive, locked, missing, or belongs to another organization.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"path","description":"Path ID of the definition that owns the new schedule."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Optional schedule display name, 1-200 characters when provided."},"triggerType":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"],"description":"Required trigger family: `CRON`, `INTERVAL`, `EVENT`, `WEBHOOK`, `MANUAL`, or `DEPENDENCY`."},"cronExpression":{"type":"string","minLength":1,"maxLength":120,"description":"Required for `CRON` schedules; 1-120 characters and used to compute `nextRunAt`."},"intervalMinutes":{"type":"integer","minimum":1,"maximum":525600,"description":"Required for `INTERVAL` schedules; 1-525600 minutes."},"timezone":{"type":"string","minLength":1,"maxLength":100,"default":"America/New_York","description":"Timezone used for cron calculations, 1-100 characters; defaults to `America/New_York`."},"blackoutWindows":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":50,"description":"Optional array of blackout-window configuration objects, up to 50 entries."},"eventTrigger":{"type":"string","minLength":1,"maxLength":200,"description":"Optional event key for event-triggered schedules, 1-200 characters."},"webhookSecret":{"type":"string","minLength":16,"maxLength":512,"description":"Optional caller-provided webhook secret, 16-512 characters. Create/update responses omit it."},"inputParams":{"type":"object","additionalProperties":{},"description":"Optional runtime parameters supplied to scheduled executions; avoid PHI and raw portal payloads."},"credentialId":{"type":"string","minLength":1,"description":"Optional automation credential ID owned by the same organization."},"maxConcurrentRuns":{"type":"integer","minimum":1,"maximum":50,"default":1,"description":"Optional concurrency cap for this schedule, 1-50; defaults to 1."},"retryOnFailure":{"type":"boolean","default":true,"description":"Optional boolean controlling whether failed scheduled runs should retry; defaults to true."},"maxRetries":{"type":"integer","minimum":0,"maximum":10,"default":3,"description":"Optional maximum retry count, 0-10; defaults to 3."},"priority":{"type":"string","enum":["HIGH","NORMAL","LOW"],"default":"NORMAL","description":"Optional run priority: `HIGH`, `NORMAL`, or `LOW`; defaults to `NORMAL`."},"deadlineMinutes":{"type":"integer","minimum":1,"maximum":10080,"description":"Optional deadline window for scheduled work, 1-10080 minutes."},"alertOnFailure":{"type":"boolean","default":true,"description":"Optional boolean controlling failure alerting; defaults to true."},"alertEmails":{"type":"array","items":{"type":"string","format":"email"},"maxItems":50,"default":[],"description":"Optional alert recipient emails, up to 50 addresses; use operational addresses only."},"pauseAfterFailures":{"type":"integer","minimum":1,"maximum":100,"default":3,"description":"Optional consecutive failure threshold, 1-100; defaults to 3."},"dependsOnScheduleId":{"type":"string","minLength":1,"description":"Optional schedule dependency ID that must belong to the same organization."},"isActive":{"type":"boolean","default":true,"description":"Optional active-state toggle for the schedule; defaults to true."}},"required":["triggerType"]},"example":{"triggerType":"CRON","name":"Example agent_builder_schedule","cronExpression":"example-cronexpression","intervalMinutes":1,"timezone":"America/New_York","blackoutWindows":[{}],"eventTrigger":"example-eventtrigger","webhookSecret":"example-webhooksecret","inputParams":{}}}},"description":"`CRON` schedules require `cronExpression`; `INTERVAL` schedules require `intervalMinutes`. Avoid placing PHI, secrets, raw payer payloads, or portal credentials in `inputParams`, `webhookSecret`, or alert fields."},"responses":{"201":{"description":"Agent schedule created for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"schedule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"name":{"type":["string","null"]},"triggerType":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"]},"cronExpression":{"type":["string","null"]},"intervalMinutes":{"type":["integer","null"]},"timezone":{"type":"string"},"isActive":{"type":"boolean"},"nextRunAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","name","triggerType","cronExpression","intervalMinutes","timezone","isActive","nextRunAt","createdAt","updatedAt"]}},"required":["mode","schedule"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","schedule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_schedule","triggerType":"CRON","cronExpression":"example-cronexpression","intervalMinutes":1,"timezone":"example-timezone","isActive":true,"nextRunAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/schedules/{scheduleId}":{"put":{"operationId":"updateAgentBuilderSchedule","summary":"Update agent schedule","description":"Updates an organization-owned Agent Builder schedule and returns safe schedule metadata.\n\n### When to use\nUse this to change trigger configuration, credentials, inputs, alert settings, dependencies, or active state for an existing schedule.\n\n### Before calling\nLoad the current schedule and decide whether changing trigger, cron expression, interval, or timezone should recompute `nextRunAt`.\n\n### Request guidance\nSend only the fields you intend to change. Do not use schedule input parameters, webhook secrets, or alert emails to store PHI or credentials.\n\n### Request notes\n- `name`, `cronExpression`, `intervalMinutes`, `blackoutWindows`, `eventTrigger`, `webhookSecret`, `inputParams`, `credentialId`, `deadlineMinutes`, and `dependsOnScheduleId` may be nullable according to the update schema.\n- `maxConcurrentRuns` remains constrained to 1-50, `maxRetries` to 0-10, `deadlineMinutes` to 1-10080, and `pauseAfterFailures` to 1-100.\n- Create/update schedule can accept a caller-provided `webhookSecret`, but only `rotateAgentBuilderScheduleWebhookSecret` generates and returns a display-once `webhookSecret`.\n\n### Response semantics\nA 200 response returns `SAFE_WRITE_DB_ONLY` schedule metadata. Sensitive schedule configuration remains omitted from the response schema.\n\n### Response notes\n- Response metadata confirms the visible schedule state only.\n- Secrets, alert email lists, runtime input parameters, retry settings, and blackout windows are not returned.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant schedule. If an update timeout occurs, read the schedule before retrying to avoid overwriting concurrent admin changes.\n\n### Error notes\n- 400 can indicate invalid cron, missing dependency schedule, or invalid credential state.\n- 403 means missing automation admin write permission.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"scheduleId","in":"path","description":"Path ID of the schedule to update."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"Optional replacement schedule name or null to clear where accepted, 1-200 characters."},"triggerType":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"],"description":"Optional replacement trigger family."},"cronExpression":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional replacement cron expression or null; 1-120 characters when provided."},"intervalMinutes":{"type":["integer","null"],"minimum":1,"maximum":525600,"description":"Optional replacement interval or null; 1-525600 minutes when provided."},"timezone":{"type":"string","minLength":1,"maxLength":100,"description":"Optional replacement timezone, 1-100 characters."},"blackoutWindows":{"type":["array","null"],"items":{"type":"object","additionalProperties":{}},"maxItems":50,"description":"Optional replacement blackout-window array or null; up to 50 entries."},"eventTrigger":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"Optional replacement event key or null, 1-200 characters."},"webhookSecret":{"type":["string","null"],"minLength":16,"maxLength":512,"description":"Optional caller-provided replacement webhook secret or null, 16-512 characters; the response does not return it."},"inputParams":{"type":["object","null"],"additionalProperties":{},"description":"Optional replacement runtime input object or null; treat as sensitive."},"credentialId":{"type":["string","null"],"minLength":1,"description":"Optional replacement credential ID or null to clear the link when accepted."},"maxConcurrentRuns":{"type":"integer","minimum":1,"maximum":50,"description":"Optional replacement concurrency cap, 1-50."},"retryOnFailure":{"type":"boolean","description":"Optional replacement retry-on-failure toggle."},"maxRetries":{"type":"integer","minimum":0,"maximum":10,"description":"Optional replacement maximum retry count, 0-10."},"priority":{"type":"string","enum":["HIGH","NORMAL","LOW"],"description":"Optional replacement run priority: `HIGH`, `NORMAL`, or `LOW`."},"deadlineMinutes":{"type":["integer","null"],"minimum":1,"maximum":10080,"description":"Optional replacement deadline window or null, 1-10080 minutes when provided."},"alertOnFailure":{"type":"boolean","description":"Optional replacement failure-alert toggle."},"alertEmails":{"type":"array","items":{"type":"string","format":"email"},"maxItems":50,"description":"Optional replacement alert recipient list, up to 50 email addresses."},"pauseAfterFailures":{"type":"integer","minimum":1,"maximum":100,"description":"Optional replacement consecutive failure threshold, 1-100."},"dependsOnScheduleId":{"type":["string","null"],"minLength":1,"description":"Optional replacement dependency schedule ID or null."},"isActive":{"type":"boolean","description":"Optional active-state toggle; when reactivated, consecutive failure count may be reset by the implementation."}}},"example":{"name":"Example agent_builder_schedule","triggerType":"CRON","cronExpression":"example-cronexpression","intervalMinutes":1,"timezone":"example-timezone","blackoutWindows":[{}],"eventTrigger":"example-eventtrigger","webhookSecret":"example-webhooksecret"}}},"description":"Send only the fields you intend to change. Do not use schedule input parameters, webhook secrets, or alert emails to store PHI or credentials."},"responses":{"200":{"description":"Agent schedule updated for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"schedule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"name":{"type":["string","null"]},"triggerType":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"]},"cronExpression":{"type":["string","null"]},"intervalMinutes":{"type":["integer","null"]},"timezone":{"type":"string"},"isActive":{"type":"boolean"},"nextRunAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","name","triggerType","cronExpression","intervalMinutes","timezone","isActive","nextRunAt","createdAt","updatedAt"]}},"required":["mode","schedule"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","schedule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_schedule","triggerType":"CRON","cronExpression":"example-cronexpression","intervalMinutes":1,"timezone":"example-timezone","isActive":true,"nextRunAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"get":{"operationId":"getAgentBuilderSchedule","summary":"Get agent schedule","description":"Retrieves safe metadata for one organization-scoped Agent Builder schedule.\n\n### When to use\nUse this before changing schedule state or reconciling an external scheduler view.\n\n### Before calling\nUse a `scheduleId` returned by an Agent Builder schedule list/create/update response for the same organization.\n\n### Request guidance\nPass the path ID only; no request body is accepted.\n\n### Request notes\n- Use a `scheduleId` returned by Agent Builder schedule list or create responses.\n- No request body is accepted.\n\n### Response semantics\nA 200 response returns `SAFE_READ_DB_ONLY` schedule metadata without secrets, credential details, alert emails, or input parameters.\n\n### Response notes\n- `data.mode` is `SAFE_READ_DB_ONLY`.\n- The response includes safe scheduling metadata only and omits secrets and runtime input parameters.\n\n### Errors and retries\nA 404 means the schedule is missing or outside the authenticated organization.\n\n### Error notes\n- 404 can mean the schedule is missing or outside the authenticated organization.\n- 403 means the caller lacks Agent Builder read access.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"scheduleId","in":"path","description":"Path ID for the organization-owned schedule."}],"responses":{"200":{"description":"Agent schedule for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"schedule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"name":{"type":["string","null"]},"triggerType":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"]},"cronExpression":{"type":["string","null"]},"intervalMinutes":{"type":["integer","null"]},"timezone":{"type":"string"},"isActive":{"type":"boolean"},"nextRunAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","name","triggerType","cronExpression","intervalMinutes","timezone","isActive","nextRunAt","createdAt","updatedAt"]}},"required":["mode","schedule"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","schedule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_schedule","triggerType":"CRON","cronExpression":"example-cronexpression","intervalMinutes":1,"timezone":"example-timezone","isActive":true,"nextRunAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"delete":{"operationId":"deleteAgentBuilderSchedule","summary":"Delete agent schedule","description":"Deletes an organization-scoped Agent Builder schedule and returns a deletion confirmation.\n\n### When to use\nUse this to remove a schedule that should no longer create future Agent Builder work.\n\n### Before calling\nConfirm the schedule is no longer needed and that dependency relationships have been reviewed.\n\n### Request guidance\nPass the path ID only; no request body is accepted.\n\n### Request notes\n- Use this only when future runs should be permanently removed rather than paused.\n- No request body is accepted.\n\n### Response semantics\nA 200 response confirms the schedule delete in the authenticated organization.\n\n### Response notes\n- `data.mode` is `SAFE_WRITE_DB_ONLY`.\n- The success body returns `scheduleId` and `deleted: true` rather than full schedule metadata.\n\n### Errors and retries\nTreat 404 as already absent or wrong organization; avoid blind retry loops for destructive requests.\n\n### Error notes\n- 404 can mean the schedule is missing or outside the authenticated organization.\n- 403 means the caller lacks automation admin write permission.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"scheduleId","in":"path","description":"Path ID for the organization-owned schedule to delete."}],"responses":{"200":{"description":"Agent schedule deleted for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"scheduleId":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["mode","scheduleId","deleted"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","scheduleId":"00000000-0000-4000-8000-000000000001","deleted":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/schedules/{scheduleId}/pause":{"post":{"operationId":"pauseAgentBuilderSchedule","summary":"Pause agent schedule","description":"Sets an organization-owned Agent Builder schedule inactive and returns safe schedule metadata.\n\n### When to use\nUse this for temporary operational holds without deleting schedule configuration.\n\n### Before calling\nConfirm callers understand future runs will not be scheduled while inactive.\n\n### Request guidance\nPass the path ID only; no request body is accepted.\n\n### Request notes\n- Use a path `scheduleId`; no request body is accepted.\n- Pause instead of delete when schedule configuration may be needed later.\n\n### Response semantics\nA 200 response returns `SAFE_WRITE_DB_ONLY` metadata with inactive schedule state.\n\n### Response notes\n- `data.mode` is `SAFE_WRITE_DB_ONLY`.\n- The returned schedule metadata should show `isActive: false` after a successful pause.\n\n### Errors and retries\nA 404 means the schedule is missing or belongs to another organization.\n\n### Error notes\n- 404 can mean the schedule is missing or outside the authenticated organization.\n- Retry 429 only after rate-limit backoff.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"scheduleId","in":"path","description":"Path ID for the organization-owned schedule to pause."}],"responses":{"200":{"description":"Agent schedule paused for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"schedule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"name":{"type":["string","null"]},"triggerType":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"]},"cronExpression":{"type":["string","null"]},"intervalMinutes":{"type":["integer","null"]},"timezone":{"type":"string"},"isActive":{"type":"boolean"},"nextRunAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","name","triggerType","cronExpression","intervalMinutes","timezone","isActive","nextRunAt","createdAt","updatedAt"]}},"required":["mode","schedule"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","schedule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","name":"Example pause_agent_builder_schedule","triggerType":"CRON","cronExpression":"example-cronexpression","intervalMinutes":1,"timezone":"example-timezone","isActive":true,"nextRunAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/schedules/{scheduleId}/resume":{"post":{"operationId":"resumeAgentBuilderSchedule","summary":"Resume agent schedule","description":"Sets an organization-owned Agent Builder schedule active and returns safe schedule metadata.\n\n### When to use\nUse this after a temporary hold when future runs should resume.\n\n### Before calling\nReview trigger settings, dependencies, credential health, and alert routing before reactivating.\n\n### Request guidance\nPass the path ID only; no request body is accepted.\n\n### Request notes\n- Use a path `scheduleId`; no request body is accepted.\n- For cron schedules, resume may recompute `nextRunAt` from the stored cron expression and timezone.\n\n### Response semantics\nA 200 response returns `SAFE_WRITE_DB_ONLY` metadata with active schedule state.\n\n### Response notes\n- `data.mode` is `SAFE_WRITE_DB_ONLY`.\n- The returned schedule metadata should show `isActive: true` after a successful resume.\n\n### Errors and retries\nA 400 or 404 should be corrected before retrying; retry 429 after backoff.\n\n### Error notes\n- 400 can occur if a cron schedule cannot compute the next run from stored configuration.\n- 404 can mean the schedule is missing or outside the authenticated organization.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"scheduleId","in":"path","description":"Path ID for the organization-owned schedule to resume."}],"responses":{"200":{"description":"Agent schedule resumed for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"schedule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"name":{"type":["string","null"]},"triggerType":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"]},"cronExpression":{"type":["string","null"]},"intervalMinutes":{"type":["integer","null"]},"timezone":{"type":"string"},"isActive":{"type":"boolean"},"nextRunAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","name","triggerType","cronExpression","intervalMinutes","timezone","isActive","nextRunAt","createdAt","updatedAt"]}},"required":["mode","schedule"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","schedule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","name":"Example resume_agent_builder_schedule","triggerType":"CRON","cronExpression":"example-cronexpression","intervalMinutes":1,"timezone":"example-timezone","isActive":true,"nextRunAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/schedules/{scheduleId}/webhook-secret/rotate":{"post":{"operationId":"rotateAgentBuilderScheduleWebhookSecret","summary":"Rotate schedule webhook secret","description":"Generates a new webhook secret for an organization-owned Agent Builder schedule and returns it once.\n\n### When to use\nUse this after creating a webhook schedule, after suspected exposure, or during planned secret rotation.\n\n### Before calling\nPrepare the receiving system to store the new value immediately. Do not log the response body.\n\n### Request guidance\nPass the path ID only; no request body is accepted.\n\n### Request notes\n- Use this only for schedules whose `triggerType` is `WEBHOOK`.\n- Store the returned `webhookSecret` immediately and do not log the response body.\n\n### Response semantics\nA 200 response returns `SAFE_WRITE_DB_ONLY`, the schedule metadata, a generated `webhookSecret`, and `displayOnce: true`. This is the only Agent Builder public endpoint in this set that returns the generated secret.\n\n### Response notes\n- `displayOnce: true` means future reads should not be expected to reveal this generated secret.\n- The schedule metadata in the response remains sanitized apart from the one-time generated secret.\n\n### Errors and retries\nRotation is only available for `WEBHOOK` schedules; non-webhook schedules return 400. If the response is lost, rotate again rather than asking the API to reveal a previously generated secret.\n\n### Error notes\n- 400 is returned when the schedule is not a `WEBHOOK` schedule.\n- If the response is lost, rotate again rather than trying to recover the previous secret.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"scheduleId","in":"path","description":"Path ID for the organization-owned webhook schedule."}],"responses":{"200":{"description":"Webhook secret rotated and displayed once.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"schedule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"name":{"type":["string","null"]},"triggerType":{"type":"string","enum":["CRON","INTERVAL","EVENT","WEBHOOK","MANUAL","DEPENDENCY"]},"cronExpression":{"type":["string","null"]},"intervalMinutes":{"type":["integer","null"]},"timezone":{"type":"string"},"isActive":{"type":"boolean"},"nextRunAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","name","triggerType","cronExpression","intervalMinutes","timezone","isActive","nextRunAt","createdAt","updatedAt"]},"webhookSecret":{"type":"string"},"displayOnce":{"type":"boolean","enum":[true]}},"required":["mode","schedule","webhookSecret","displayOnce"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","schedule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","name":"Example rotate_agent_builder_schedule_webhook_secret","triggerType":"CRON","cronExpression":"example-cronexpression","intervalMinutes":1,"timezone":"example-timezone","isActive":true,"nextRunAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"webhookSecret":"example-webhooksecret","displayOnce":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/executions":{"get":{"operationId":"listAgentBuilderExecutions","summary":"List agent executions","description":"Returns paginated, organization-scoped execution metadata for Agent Builder polling and monitoring workflows.\n\n### When to use\nUse this to monitor execution wrappers by definition, schedule, status, trigger source, or date range.\n\n### Before calling\nChoose narrow filters for long-running tenants and avoid exporting sensitive execution data into logs.\n\n### Request guidance\nUse `dateFrom` and `dateTo` as date-time filters when polling by window. Use `limit` and `offset` for pagination.\n\n### Request notes\n- Use `agentDefinitionId`, `scheduleId`, `status`, `triggeredBy`, `dateFrom`, and `dateTo` to keep polling windows narrow.\n- `dateFrom` and `dateTo` are ISO date-time bounds for execution `createdAt`.\n\n### Response semantics\nA 200 response returns `SAFE_READ_DB_ONLY` execution metadata and pagination. Detailed output and step summaries belong on execution detail/result endpoints.\n\n### Response notes\n- `data.mode` is `SAFE_READ_DB_ONLY`.\n- List responses contain execution metadata; use detail, status, or result endpoints for step summaries and scrubbed output.\n\n### Errors and retries\nRetry 429 with backoff; treat 403 as missing Agent Builder read permission.\n\n### Error notes\n- 400 means query validation failed, including malformed date-time filters.\n- Retry 429 with backoff and avoid tight polling loops.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query","description":"Maximum page size, 1 to 100; defaults to 50."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query","description":"Zero-based row offset for pagination; defaults to 0."},{"schema":{"type":"string","minLength":1},"required":false,"name":"agentDefinitionId","in":"query","description":"Optional execution filter by definition ID."},{"schema":{"type":"string","minLength":1},"required":false,"name":"scheduleId","in":"query","description":"Optional execution filter by schedule ID."},{"schema":{"type":"string","enum":["QUEUED","INITIALIZING","AUTHENTICATING","RUNNING","EXTRACTING","TRANSFORMING","COMPLETED","FAILED","CANCELLED","APPROVAL_PENDING","TIMED_OUT"]},"required":false,"name":"status","in":"query","description":"Optional execution status filter."},{"schema":{"type":"string","enum":["EXECUTION_CRON","EXECUTION_EVENT","EXECUTION_WEBHOOK","EXECUTION_MANUAL","EXECUTION_API","EXECUTION_BATCH","EXECUTION_DEPENDENCY"]},"required":false,"name":"triggeredBy","in":"query","description":"Optional filter by execution trigger source."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"dateFrom","in":"query","description":"Optional ISO date-time lower bound applied to execution `createdAt`."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"dateTo","in":"query","description":"Optional ISO date-time upper bound applied to execution `createdAt`."}],"responses":{"200":{"description":"Agent executions for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"executions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"scheduleId":{"type":["string","null"]},"status":{"type":"string","enum":["QUEUED","INITIALIZING","AUTHENTICATING","RUNNING","EXTRACTING","TRANSFORMING","COMPLETED","FAILED","CANCELLED","APPROVAL_PENDING","TIMED_OUT"]},"triggeredBy":{"type":"string","enum":["EXECUTION_CRON","EXECUTION_EVENT","EXECUTION_WEBHOOK","EXECUTION_MANUAL","EXECUTION_API","EXECUTION_BATCH","EXECUTION_DEPENDENCY"]},"credentialId":{"type":["string","null"]},"agentVersion":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","scheduleId","status","triggeredBy","credentialId","agentVersion","startedAt","completedAt","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"]}},"required":["mode","executions","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","executions":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","scheduleId":"00000000-0000-4000-8000-000000000001","status":"QUEUED","triggeredBy":"EXECUTION_CRON","credentialId":"00000000-0000-4000-8000-000000000001","agentVersion":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"pagination":{"limit":1,"offset":1,"total":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createAgentBuilderExecution","summary":"Create agent execution wrapper","description":"Creates an organization-scoped Agent Builder execution wrapper record with dry-run and queue-only safety controls.\n\n### When to use\nUse this when an external system needs to request an execution record without directly running browser automation inline.\n\n### Before calling\nResolve `agentDefinitionId` and optional `credentialId` from the authenticated organization. Prepare synthetic or minimal `inputParams` and avoid PHI.\n\n### Request guidance\nKeep either `dryRun` or `queueOnly` enabled for public safety. Do not include idempotency keys; they are not accepted by the current public schema.\n\n### Request notes\n- `agentDefinitionId` is required and must reference a non-archived definition in the authenticated organization.\n- `inputParams` defaults to an empty object. Keep examples synthetic and avoid PHI or raw portal payloads.\n- `dryRun` and `queueOnly` both default to true; at least one of them must remain true for public execution creation.\n\n### Response semantics\nA 202 response returns execution wrapper metadata with mode `SIMULATED_ONLY` when `dryRun` is true or `QUEUE_ONLY` when public queue-only controls are used, and always returns `browserAutomationStarted: false`.\n\n### Response notes\n- The public API creates an execution record; it does not start browser automation inline.\n- The execution status is usually `QUEUED`, or `APPROVAL_PENDING` for non-dry-run write-capable definitions that require approval.\n\n### Errors and retries\nOn timeout, list executions by definition and date window before creating another record. Fix validation and credential errors before retrying.\n\n### Error notes\n- 400 can mean both `dryRun` and `queueOnly` were false, the agent is archived, or a credential reference is invalid/inactive/locked.\n- 404 means the definition was not found in the authenticated organization.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agentDefinitionId":{"type":"string","minLength":1,"description":"Required ID of the organization-owned definition to execute."},"inputParams":{"type":"object","additionalProperties":{},"default":{},"description":"Optional runtime input object; keep PHI and raw portal data out of examples and logs."},"credentialId":{"type":"string","minLength":1,"description":"Optional organization-owned automation credential override."},"dryRun":{"type":"boolean","default":true,"description":"Execution safety control. When true, public execution responses use simulated mode."},"queueOnly":{"type":"boolean","default":true,"description":"Execution safety control. Public callers use it to create or queue work without inline browser automation."}},"required":["agentDefinitionId"],"additionalProperties":false},"example":{"agentDefinitionId":"00000000-0000-4000-8000-000000000001","inputParams":{},"credentialId":"00000000-0000-4000-8000-000000000001","dryRun":true,"queueOnly":true}}},"description":"Keep either `dryRun` or `queueOnly` enabled for public safety. Do not include idempotency keys; they are not accepted by the current public schema."},"responses":{"202":{"description":"Agent execution record created without inline browser automation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY","QUEUE_ONLY"]},"controls":{"type":"object","properties":{"dryRun":{"type":"boolean"},"queueOnly":{"type":"boolean"},"browserAutomationStarted":{"type":"boolean","enum":[false]}},"required":["dryRun","queueOnly","browserAutomationStarted"]},"execution":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"scheduleId":{"type":["string","null"]},"status":{"type":"string","enum":["QUEUED","INITIALIZING","AUTHENTICATING","RUNNING","EXTRACTING","TRANSFORMING","COMPLETED","FAILED","CANCELLED","APPROVAL_PENDING","TIMED_OUT"]},"triggeredBy":{"type":"string","enum":["EXECUTION_CRON","EXECUTION_EVENT","EXECUTION_WEBHOOK","EXECUTION_MANUAL","EXECUTION_API","EXECUTION_BATCH","EXECUTION_DEPENDENCY"]},"credentialId":{"type":["string","null"]},"agentVersion":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","scheduleId","status","triggeredBy","credentialId","agentVersion","startedAt","completedAt","createdAt","updatedAt"]}},"required":["mode","controls","execution"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","controls":{"dryRun":true,"queueOnly":true,"browserAutomationStarted":false},"execution":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","scheduleId":"00000000-0000-4000-8000-000000000001","status":"QUEUED","triggeredBy":"EXECUTION_CRON","credentialId":"00000000-0000-4000-8000-000000000001","agentVersion":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/executions/{executionId}":{"get":{"operationId":"getAgentBuilderExecution","summary":"Get agent execution","description":"Retrieves a detailed, organization-scoped Agent Builder execution record with scrubbed output data and execution metadata.\n\n### When to use\nUse this for an operator detail view or integration reconciliation after creating or polling executions.\n\n### Before calling\nUse an `executionId` returned by this organization and treat returned output as sensitive even after known field scrubbing.\n\n### Request guidance\nPass the path ID only; no request body is accepted.\n\n### Request notes\n- Use an `executionId` returned by create, retry, or list operations in the same tenant context.\n- No request body is accepted.\n\n### Response semantics\nA 200 response returns execution details for the authenticated organization. Known PHI-like fields may be scrubbed, but the result should still be handled as sensitive.\n\n### Response notes\n- `data.mode` is `SAFE_READ_DB_ONLY`.\n- The detail response can include scrubbed `outputData`, step summaries, screenshot metadata, and entity-change summaries.\n\n### Errors and retries\nA 404 means the execution is missing or outside the authenticated organization.\n\n### Error notes\n- 404 can mean the execution is missing or outside the authenticated organization.\n- Treat output as sensitive even when known PHI-like fields are scrubbed.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"executionId","in":"path","description":"Path ID for the organization-owned execution."}],"responses":{"200":{"description":"Agent execution for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"execution":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"scheduleId":{"type":["string","null"]},"status":{"type":"string","enum":["QUEUED","INITIALIZING","AUTHENTICATING","RUNNING","EXTRACTING","TRANSFORMING","COMPLETED","FAILED","CANCELLED","APPROVAL_PENDING","TIMED_OUT"]},"triggeredBy":{"type":"string","enum":["EXECUTION_CRON","EXECUTION_EVENT","EXECUTION_WEBHOOK","EXECUTION_MANUAL","EXECUTION_API","EXECUTION_BATCH","EXECUTION_DEPENDENCY"]},"credentialId":{"type":["string","null"]},"agentVersion":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"outputSummary":{"type":["string","null"]},"outputData":{"type":["object","null"],"additionalProperties":{}},"extractedRecords":{"type":"integer"},"transformedRecords":{"type":"integer"},"linkedEntities":{"type":"integer"},"creditsCharged":{"type":"number"},"llmTokensUsed":{"type":"integer"},"durationMs":{"type":["integer","null"]},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"failedAtStep":{"type":["integer","null"]},"batchId":{"type":["string","null"]},"batchIndex":{"type":["integer","null"]},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stepIndex":{"type":"integer"},"stepType":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"durationMs":{"type":["integer","null"]},"llmTokensUsed":{"type":"integer"},"errorMessage":{"type":["string","null"]},"retryCount":{"type":"integer"}},"required":["id","stepIndex","stepType","status","startedAt","completedAt","durationMs","llmTokensUsed","errorMessage","retryCount"]}},"screenshots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stepIndex":{"type":"integer"},"timing":{"type":"string"},"contentType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","stepIndex","timing","contentType","createdAt"]}},"entityChanges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"entityType":{"type":"string"},"entityId":{"type":["string","null"]},"action":{"type":"string"},"validationPassed":{"type":"boolean"},"validationErrors":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","entityType","entityId","action","validationPassed","validationErrors","createdAt"]}}},"required":["id","organizationId","agentDefinitionId","scheduleId","status","triggeredBy","credentialId","agentVersion","startedAt","completedAt","createdAt","updatedAt","outputSummary","outputData","extractedRecords","transformedRecords","linkedEntities","creditsCharged","llmTokensUsed","durationMs","errorCode","errorMessage","failedAtStep","batchId","batchIndex","steps","screenshots","entityChanges"]}},"required":["mode","execution"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","execution":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","scheduleId":"00000000-0000-4000-8000-000000000001","status":"QUEUED","triggeredBy":"EXECUTION_CRON","credentialId":"00000000-0000-4000-8000-000000000001","agentVersion":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","outputSummary":"example-outputsummary","outputData":{},"extractedRecords":1,"transformedRecords":1,"linkedEntities":1,"creditsCharged":125.5,"llmTokensUsed":1,"durationMs":1,"errorCode":"example-errorcode","errorMessage":"example-errormessage","failedAtStep":1,"batchId":"00000000-0000-4000-8000-000000000001","batchIndex":1,"steps":[{"id":"00000000-0000-4000-8000-000000000001","stepIndex":1,"stepType":"example-steptype","status":"active","startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","durationMs":1,"llmTokensUsed":1,"errorMessage":"example-errormessage","retryCount":1}],"screenshots":[{"id":"00000000-0000-4000-8000-000000000001","stepIndex":1,"timing":"example-timing","contentType":"example-contenttype","createdAt":"2026-06-08T10:15:30Z"}],"entityChanges":[{"id":"00000000-0000-4000-8000-000000000001","entityType":"example-entitytype","entityId":"00000000-0000-4000-8000-000000000001","action":"example-action","validationPassed":true,"validationErrors":["example-validationerrors"],"createdAt":"2026-06-08T10:15:30Z"}]}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/executions/{executionId}/status":{"get":{"operationId":"getAgentBuilderExecutionStatus","summary":"Get agent execution status","description":"Retrieves the current organization-scoped execution detail payload for status polling.\n\n### When to use\nUse this when a client primarily needs status updates for an existing execution.\n\n### Before calling\nUse a known `executionId` from the authenticated organization.\n\n### Request guidance\nPass the path ID only. Poll at a reasonable interval and respect 429 responses.\n\n### Request notes\n- Use this route for polling an existing execution by ID.\n- No request body is accepted.\n\n### Response semantics\nThe current public operation returns the same execution-detail style payload as the execution detail endpoint, not a separate minimal status schema.\n\n### Response notes\n- The current response shape is execution-detail style rather than a minimal status-only schema.\n- Clients should read the `execution.status` field from the returned detail payload.\n\n### Errors and retries\nStop polling on terminal states or 404; retry 429 with backoff.\n\n### Error notes\n- 404 can mean the execution is missing or outside the authenticated organization.\n- Use backoff for polling and 429 responses.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"executionId","in":"path","description":"Path ID for the organization-owned execution."}],"responses":{"200":{"description":"Agent execution status for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"execution":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"scheduleId":{"type":["string","null"]},"status":{"type":"string","enum":["QUEUED","INITIALIZING","AUTHENTICATING","RUNNING","EXTRACTING","TRANSFORMING","COMPLETED","FAILED","CANCELLED","APPROVAL_PENDING","TIMED_OUT"]},"triggeredBy":{"type":"string","enum":["EXECUTION_CRON","EXECUTION_EVENT","EXECUTION_WEBHOOK","EXECUTION_MANUAL","EXECUTION_API","EXECUTION_BATCH","EXECUTION_DEPENDENCY"]},"credentialId":{"type":["string","null"]},"agentVersion":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"outputSummary":{"type":["string","null"]},"outputData":{"type":["object","null"],"additionalProperties":{}},"extractedRecords":{"type":"integer"},"transformedRecords":{"type":"integer"},"linkedEntities":{"type":"integer"},"creditsCharged":{"type":"number"},"llmTokensUsed":{"type":"integer"},"durationMs":{"type":["integer","null"]},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"failedAtStep":{"type":["integer","null"]},"batchId":{"type":["string","null"]},"batchIndex":{"type":["integer","null"]},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stepIndex":{"type":"integer"},"stepType":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"durationMs":{"type":["integer","null"]},"llmTokensUsed":{"type":"integer"},"errorMessage":{"type":["string","null"]},"retryCount":{"type":"integer"}},"required":["id","stepIndex","stepType","status","startedAt","completedAt","durationMs","llmTokensUsed","errorMessage","retryCount"]}},"screenshots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stepIndex":{"type":"integer"},"timing":{"type":"string"},"contentType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","stepIndex","timing","contentType","createdAt"]}},"entityChanges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"entityType":{"type":"string"},"entityId":{"type":["string","null"]},"action":{"type":"string"},"validationPassed":{"type":"boolean"},"validationErrors":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","entityType","entityId","action","validationPassed","validationErrors","createdAt"]}}},"required":["id","organizationId","agentDefinitionId","scheduleId","status","triggeredBy","credentialId","agentVersion","startedAt","completedAt","createdAt","updatedAt","outputSummary","outputData","extractedRecords","transformedRecords","linkedEntities","creditsCharged","llmTokensUsed","durationMs","errorCode","errorMessage","failedAtStep","batchId","batchIndex","steps","screenshots","entityChanges"]}},"required":["mode","execution"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","execution":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","scheduleId":"00000000-0000-4000-8000-000000000001","status":"QUEUED","triggeredBy":"EXECUTION_CRON","credentialId":"00000000-0000-4000-8000-000000000001","agentVersion":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","outputSummary":"example-outputsummary","outputData":{},"extractedRecords":1,"transformedRecords":1,"linkedEntities":1,"creditsCharged":125.5,"llmTokensUsed":1,"durationMs":1,"errorCode":"example-errorcode","errorMessage":"example-errormessage","failedAtStep":1,"batchId":"00000000-0000-4000-8000-000000000001","batchIndex":1,"steps":[{"id":"00000000-0000-4000-8000-000000000001","stepIndex":1,"stepType":"example-steptype","status":"active","startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","durationMs":1,"llmTokensUsed":1,"errorMessage":"example-errormessage","retryCount":1}],"screenshots":[{"id":"00000000-0000-4000-8000-000000000001","stepIndex":1,"timing":"example-timing","contentType":"example-contenttype","createdAt":"2026-06-08T10:15:30Z"}],"entityChanges":[{"id":"00000000-0000-4000-8000-000000000001","entityType":"example-entitytype","entityId":"00000000-0000-4000-8000-000000000001","action":"example-action","validationPassed":true,"validationErrors":["example-validationerrors"],"createdAt":"2026-06-08T10:15:30Z"}]}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/executions/{executionId}/result":{"get":{"operationId":"getAgentBuilderExecutionResult","summary":"Get agent execution result","description":"Retrieves the current organization-scoped execution detail payload for result inspection.\n\n### When to use\nUse this when a client primarily needs output, step summaries, screenshots metadata, or entity-change summaries after execution work completes.\n\n### Before calling\nUse a known `executionId` and avoid logging returned output data.\n\n### Request guidance\nPass the path ID only. Prefer fetching results after the execution reaches a terminal state.\n\n### Request notes\n- Use this route after an execution reaches a terminal or reviewable state.\n- No request body is accepted.\n\n### Response semantics\nThe current public operation returns the same execution-detail style payload as the execution detail endpoint. Treat output as sensitive even after known field scrubbing.\n\n### Response notes\n- The current response shape is execution-detail style and may include scrubbed output plus step/entity summaries.\n- Treat returned output as sensitive workflow data.\n\n### Errors and retries\nIf the execution is not complete, poll status before retrying result reads.\n\n### Error notes\n- 404 can mean the execution is missing or outside the authenticated organization.\n- Do not assume output is PHI-free merely because known PHI-like fields may be scrubbed.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"executionId","in":"path","description":"Path ID for the organization-owned execution."}],"responses":{"200":{"description":"Agent execution result for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"execution":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"scheduleId":{"type":["string","null"]},"status":{"type":"string","enum":["QUEUED","INITIALIZING","AUTHENTICATING","RUNNING","EXTRACTING","TRANSFORMING","COMPLETED","FAILED","CANCELLED","APPROVAL_PENDING","TIMED_OUT"]},"triggeredBy":{"type":"string","enum":["EXECUTION_CRON","EXECUTION_EVENT","EXECUTION_WEBHOOK","EXECUTION_MANUAL","EXECUTION_API","EXECUTION_BATCH","EXECUTION_DEPENDENCY"]},"credentialId":{"type":["string","null"]},"agentVersion":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"outputSummary":{"type":["string","null"]},"outputData":{"type":["object","null"],"additionalProperties":{}},"extractedRecords":{"type":"integer"},"transformedRecords":{"type":"integer"},"linkedEntities":{"type":"integer"},"creditsCharged":{"type":"number"},"llmTokensUsed":{"type":"integer"},"durationMs":{"type":["integer","null"]},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"failedAtStep":{"type":["integer","null"]},"batchId":{"type":["string","null"]},"batchIndex":{"type":["integer","null"]},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stepIndex":{"type":"integer"},"stepType":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"durationMs":{"type":["integer","null"]},"llmTokensUsed":{"type":"integer"},"errorMessage":{"type":["string","null"]},"retryCount":{"type":"integer"}},"required":["id","stepIndex","stepType","status","startedAt","completedAt","durationMs","llmTokensUsed","errorMessage","retryCount"]}},"screenshots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"stepIndex":{"type":"integer"},"timing":{"type":"string"},"contentType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","stepIndex","timing","contentType","createdAt"]}},"entityChanges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"entityType":{"type":"string"},"entityId":{"type":["string","null"]},"action":{"type":"string"},"validationPassed":{"type":"boolean"},"validationErrors":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","entityType","entityId","action","validationPassed","validationErrors","createdAt"]}}},"required":["id","organizationId","agentDefinitionId","scheduleId","status","triggeredBy","credentialId","agentVersion","startedAt","completedAt","createdAt","updatedAt","outputSummary","outputData","extractedRecords","transformedRecords","linkedEntities","creditsCharged","llmTokensUsed","durationMs","errorCode","errorMessage","failedAtStep","batchId","batchIndex","steps","screenshots","entityChanges"]}},"required":["mode","execution"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","execution":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","scheduleId":"00000000-0000-4000-8000-000000000001","status":"QUEUED","triggeredBy":"EXECUTION_CRON","credentialId":"00000000-0000-4000-8000-000000000001","agentVersion":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","outputSummary":"example-outputsummary","outputData":{},"extractedRecords":1,"transformedRecords":1,"linkedEntities":1,"creditsCharged":125.5,"llmTokensUsed":1,"durationMs":1,"errorCode":"example-errorcode","errorMessage":"example-errormessage","failedAtStep":1,"batchId":"00000000-0000-4000-8000-000000000001","batchIndex":1,"steps":[{"id":"00000000-0000-4000-8000-000000000001","stepIndex":1,"stepType":"example-steptype","status":"active","startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","durationMs":1,"llmTokensUsed":1,"errorMessage":"example-errormessage","retryCount":1}],"screenshots":[{"id":"00000000-0000-4000-8000-000000000001","stepIndex":1,"timing":"example-timing","contentType":"example-contenttype","createdAt":"2026-06-08T10:15:30Z"}],"entityChanges":[{"id":"00000000-0000-4000-8000-000000000001","entityType":"example-entitytype","entityId":"00000000-0000-4000-8000-000000000001","action":"example-action","validationPassed":true,"validationErrors":["example-validationerrors"],"createdAt":"2026-06-08T10:15:30Z"}]}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/executions/{executionId}/cancel":{"post":{"operationId":"cancelAgentBuilderExecution","summary":"Cancel agent execution","description":"Requests cancellation for an organization-owned Agent Builder execution and returns safe execution metadata.\n\n### When to use\nUse this when queued or running work should be stopped from an external control plane.\n\n### Before calling\nConfirm the execution belongs to the authenticated organization and is not already terminal.\n\n### Request guidance\n`reason` is accepted for caller context, but do not rely on it being persisted or returned unless the applied implementation documents that behavior.\n\n### Request notes\n- `reason` is optional and capped at 1000 characters; keep it non-PHI and operational.\n- Only queued, initializing, authenticating, running, extracting, transforming, or approval-pending executions are cancellable.\n\n### Response semantics\nA 200 response returns `SAFE_WRITE_DB_ONLY` execution metadata after cancellation handling.\n\n### Response notes\n- `data.mode` is `SAFE_WRITE_DB_ONLY`.\n- The response returns safe execution metadata after the status update; it does not promise later retrieval of the supplied reason.\n\n### Errors and retries\nA 400 can indicate an invalid state transition. A 404 means the execution is missing or outside the authenticated organization.\n\n### Error notes\n- 400 is returned when the execution is already in a non-cancellable status.\n- 404 can mean the execution is missing or outside the authenticated organization.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"executionId","in":"path","description":"Path ID for the organization-owned execution to cancel."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional cancellation reason for caller context; keep it non-PHI and do not assume it is persisted."}}},"example":{"reason":"example-reason"}}},"description":"`reason` is accepted for caller context, but do not rely on it being persisted or returned unless the applied implementation documents that behavior."},"responses":{"200":{"description":"Agent execution cancelled for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"execution":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"scheduleId":{"type":["string","null"]},"status":{"type":"string","enum":["QUEUED","INITIALIZING","AUTHENTICATING","RUNNING","EXTRACTING","TRANSFORMING","COMPLETED","FAILED","CANCELLED","APPROVAL_PENDING","TIMED_OUT"]},"triggeredBy":{"type":"string","enum":["EXECUTION_CRON","EXECUTION_EVENT","EXECUTION_WEBHOOK","EXECUTION_MANUAL","EXECUTION_API","EXECUTION_BATCH","EXECUTION_DEPENDENCY"]},"credentialId":{"type":["string","null"]},"agentVersion":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","scheduleId","status","triggeredBy","credentialId","agentVersion","startedAt","completedAt","createdAt","updatedAt"]}},"required":["mode","execution"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","execution":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","scheduleId":"00000000-0000-4000-8000-000000000001","status":"QUEUED","triggeredBy":"EXECUTION_CRON","credentialId":"00000000-0000-4000-8000-000000000001","agentVersion":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/executions/{executionId}/retry":{"post":{"operationId":"retryAgentBuilderExecution","summary":"Retry agent execution wrapper","description":"Creates a new safe retry execution record for an organization-owned Agent Builder execution using dry-run and queue-only controls.\n\n### When to use\nUse this only when the original execution is in `FAILED` or `TIMED_OUT` status and retrying is operationally appropriate.\n\n### Before calling\nInspect the original execution, confirm retry is appropriate, and decide whether the retry should be dry-run or queue-only.\n\n### Request guidance\nKeep either `dryRun` or `queueOnly` enabled. Do not include credentials, PHI, or idempotency keys in the body.\n\n### Request notes\n- `executionId` must reference an execution owned by the authenticated organization.\n- Only executions in `FAILED` or `TIMED_OUT` status are retryable by this handler.\n- `dryRun` and `queueOnly` both default to true; at least one must remain true.\n\n### Response semantics\nA 202 response returns the new retry execution wrapper with mode `SIMULATED_ONLY` or `QUEUE_ONLY`, plus `browserAutomationStarted: false`.\n\n### Response notes\n- The response contains the newly created retry execution record, not the original execution.\n- Browser automation is not started inline by the public retry endpoint.\n\n### Errors and retries\nAvoid retry loops. Fix credential, validation, or workflow configuration errors before requesting another retry.\n\n### Error notes\n- 400 is returned when the original status is not `FAILED` or `TIMED_OUT`, when both safety controls are false, or when the linked agent is archived.\n- 404 can mean the execution or linked agent definition is missing in the authenticated organization.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"executionId","in":"path","description":"Path ID for the organization-owned execution to retry."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":true,"description":"Retry safety control for simulated behavior."},"queueOnly":{"type":"boolean","default":true,"description":"Retry safety control for queue-only behavior."}},"additionalProperties":false},"example":{"dryRun":true,"queueOnly":true}}},"description":"Keep either `dryRun` or `queueOnly` enabled. Do not include credentials, PHI, or idempotency keys in the body."},"responses":{"202":{"description":"Retry execution record created without inline browser automation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY","QUEUE_ONLY"]},"controls":{"type":"object","properties":{"dryRun":{"type":"boolean"},"queueOnly":{"type":"boolean"},"browserAutomationStarted":{"type":"boolean","enum":[false]}},"required":["dryRun","queueOnly","browserAutomationStarted"]},"execution":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agentDefinitionId":{"type":"string"},"scheduleId":{"type":["string","null"]},"status":{"type":"string","enum":["QUEUED","INITIALIZING","AUTHENTICATING","RUNNING","EXTRACTING","TRANSFORMING","COMPLETED","FAILED","CANCELLED","APPROVAL_PENDING","TIMED_OUT"]},"triggeredBy":{"type":"string","enum":["EXECUTION_CRON","EXECUTION_EVENT","EXECUTION_WEBHOOK","EXECUTION_MANUAL","EXECUTION_API","EXECUTION_BATCH","EXECUTION_DEPENDENCY"]},"credentialId":{"type":["string","null"]},"agentVersion":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agentDefinitionId","scheduleId","status","triggeredBy","credentialId","agentVersion","startedAt","completedAt","createdAt","updatedAt"]}},"required":["mode","controls","execution"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","controls":{"dryRun":true,"queueOnly":true,"browserAutomationStarted":false},"execution":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agentDefinitionId":"00000000-0000-4000-8000-000000000001","scheduleId":"00000000-0000-4000-8000-000000000001","status":"QUEUED","triggeredBy":"EXECUTION_CRON","credentialId":"00000000-0000-4000-8000-000000000001","agentVersion":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/credentials":{"get":{"operationId":"listAgentBuilderCredentials","summary":"List automation credentials","description":"Returns paginated safe metadata for automation credentials that can be referenced by Agent Builder definitions, schedules, template installs, or executions.\n\n### When to use\nUse this to resolve a credential ID by portal type or identifier before referencing it in another Agent Builder public request.\n\n### Before calling\nAuthenticate with Agent Builder read access and decide whether inactive or locked credentials should be included.\n\n### Request guidance\nFilter by `portalType`, `portalIdentifier`, or `activeOnly`. Do not expect usernames, passwords, API tokens, secret manager ARNs, or credential payloads.\n\n### Request notes\n- `activeOnly` defaults to true and excludes inactive or locked credentials unless explicitly false.\n- Use `portalType` or `portalIdentifier` to narrow credential discovery before referencing a credential ID elsewhere.\n\n### Response semantics\nA 200 response returns `SAFE_READ_DB_ONLY` credential metadata only.\n\n### Response notes\n- `data.mode` is `SAFE_READ_DB_ONLY`.\n- Responses include safe credential metadata only: no usernames, passwords, API tokens, or secret locations.\n\n### Errors and retries\nA 403 indicates missing read permission; retry 429 after backoff.\n\n### Error notes\n- 400 means query validation failed.\n- 403 means the caller lacks Agent Builder read access.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query","description":"Maximum page size, 1 to 100; defaults to 50."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query","description":"Zero-based row offset for pagination; defaults to 0."},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"portalType","in":"query","description":"Optional portal type filter for credentials."},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"portalIdentifier","in":"query","description":"Optional portal identifier filter for credentials."},{"schema":{"type":"boolean","default":true},"required":false,"name":"activeOnly","in":"query","description":"Credential list filter that defaults to true and excludes inactive or locked credentials."}],"responses":{"200":{"description":"Safe credential metadata for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"credentials":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"portalType":{"type":"string"},"portalIdentifier":{"type":"string"},"portalUrl":{"type":"string"},"isActive":{"type":"boolean"},"isLockedOut":{"type":"boolean"}},"required":["id","name","portalType","portalIdentifier","portalUrl","isActive","isLockedOut"]}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"]}},"required":["mode","credentials","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","credentials":[{"id":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_credential","portalType":"example-portaltype","portalIdentifier":"example-portalidentifier","portalUrl":"https://example.quickintell.com/resource","isActive":true,"isLockedOut":true}],"pagination":{"limit":1,"offset":1,"total":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/templates":{"get":{"operationId":"listAgentBuilderTemplates","summary":"List agent templates","description":"Lists built-in and organization-published Agent Builder templates with safe template metadata and pagination.\n\n### When to use\nUse this before installing a reusable template as a tenant-local draft definition.\n\n### Before calling\nChoose category, application type, or search filters that match the workflow catalog you want to show.\n\n### Request guidance\nUse `limit` and `offset` for pagination. Use `search` for non-PHI template metadata only.\n\n### Request notes\n- Use `category`, `applicationType`, and non-PHI `search` text to narrow template discovery.\n- Pagination applies after built-in templates and organization templates are combined and sorted by name.\n\n### Response semantics\nA 200 response returns `SAFE_READ_DB_ONLY` template metadata and intentionally omits template step bodies.\n\n### Response notes\n- `data.mode` is `SAFE_READ_DB_ONLY`.\n- Template list responses omit template step bodies and executable configuration internals.\n\n### Errors and retries\nRetry 429 after backoff and treat 403 as missing Agent Builder read permission.\n\n### Error notes\n- 400 means query validation failed.\n- 403 means the caller lacks Agent Builder read access.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query","description":"Maximum page size, 1 to 100; defaults to 50."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query","description":"Zero-based row offset for pagination; defaults to 0."},{"schema":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"required":false,"name":"category","in":"query","description":"Optional template RCM category filter."},{"schema":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"required":false,"name":"applicationType","in":"query","description":"Optional target application class filter."},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"search","in":"query","description":"Optional 1-200 character template metadata search string."}],"responses":{"200":{"description":"Agent templates for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_READ_DB_ONLY"]},"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"templateSlug":{"type":"string"},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"tags":{"type":"array","items":{"type":"string"}},"applicationName":{"type":"string"},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"]},"installCount":{"type":"integer"}},"required":["id","name","templateSlug","description","icon","category","tags","applicationName","applicationType","mode","installCount"]}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"]}},"required":["mode","templates","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_READ_DB_ONLY","templates":[{"id":"00000000-0000-4000-8000-000000000001","name":"Example agent_builder_template","templateSlug":"example-templateslug","description":"Example agent_builder_template note","icon":"example-icon","category":"ELIGIBILITY","tags":["example-tags"],"applicationName":"Example agent_builder_template","applicationType":"EHR","mode":"READ","installCount":1}],"pagination":{"limit":1,"offset":1,"total":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/templates/{templateId}/install":{"post":{"operationId":"installAgentBuilderTemplate","summary":"Install agent template","description":"Installs a built-in or organization-published template as a new draft Agent Builder definition.\n\n### When to use\nUse this to create a tenant-local draft from a safe template catalog entry.\n\n### Before calling\nResolve `templateId` from the template list and, if supplied, validate `credentialId` from the authenticated organization's credential list.\n\n### Request guidance\nOnly send an optional replacement `name` and optional credential reference. Do not send step bodies or secrets.\n\n### Request notes\n- `templateId` can refer to a built-in template slug or an organization template ID/slug.\n- `name` and `credentialId` are optional; referenced credentials must belong to the authenticated organization.\n\n### Response semantics\nA 201 response returns `SAFE_WRITE_DB_ONLY` metadata for the installed draft definition. The public response still omits installed step bodies; callers that need customization through the public API must supply replacement step configuration from their own safe source using the definition update endpoint.\n\n### Response notes\n- `data.mode` is `SAFE_WRITE_DB_ONLY`.\n- The endpoint creates a tenant-local draft definition and returns safe definition metadata, not the full installed step body.\n\n### Errors and retries\nA 404 means the template was not visible to the authenticated organization. A 409 can mean the installed definition name conflicts with an existing slug.\n\n### Error notes\n- 404 means the template was not found for the authenticated organization or built-in catalog.\n- 400 can mean the referenced credential is missing, inactive, locked, or outside the organization.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"templateId","in":"path","description":"Template path identifier; install accepts built-in template slugs and organization template IDs or slugs."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Optional replacement definition name for the installed template."},"credentialId":{"type":"string","minLength":1,"description":"Optional organization-owned automation credential reference."}}},"example":{"name":"Example install_agent_builder_template","credentialId":"00000000-0000-4000-8000-000000000001"}}},"description":"Only send an optional replacement `name` and optional credential reference. Do not send step bodies or secrets."},"responses":{"201":{"description":"Agent template installed as a draft definition.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"agentDefinition":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"applicationUrl":{"type":"string"},"applicationName":{"type":"string"},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"version":{"type":"integer"},"requiresApproval":{"type":"boolean"},"creditCost":{"type":"integer"},"tokenBudget":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"maxRetries":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","slug","description","category","applicationUrl","applicationName","applicationType","mode","status","version","requiresApproval","creditCost","tokenBudget","timeoutSeconds","maxRetries","createdAt","updatedAt"]}},"required":["mode","agentDefinition"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","agentDefinition":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example install_agent_builder_template","slug":"example-slug","description":"Example install_agent_builder_template note","category":"ELIGIBILITY","applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example install_agent_builder_template","applicationType":"EHR","mode":"READ","status":"DRAFT","version":1,"requiresApproval":true,"creditCost":1,"tokenBudget":1,"timeoutSeconds":1,"maxRetries":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/agent-builder/definitions/{agentId}/publish-template":{"post":{"operationId":"publishAgentBuilderTemplate","summary":"Publish agent definition as template","description":"Publishes an organization-owned Agent Builder definition as an organization template and returns safe definition metadata.\n\n### When to use\nUse this when a reviewed definition should become reusable through the template listing/install flow.\n\n### Before calling\nReview the definition for PHI, credentials, raw portal data, and unsafe write behavior before publishing.\n\n### Request guidance\n`templateSlug` is required, must be 1-120 characters, and should be stable, descriptive, and free of PHI. Publishing clears the definition credential linkage so the reusable template does not carry `defaultCredentialId`.\n\n### Request notes\n- `templateSlug` is required and must be unique across existing templates.\n- Review the source definition before publishing because reusable templates should not contain PHI, secrets, or unsafe write assumptions.\n\n### Response semantics\nA 200 response returns `SAFE_WRITE_DB_ONLY` with `data.agentDefinition`, not a template-list metadata object. The response omits raw step bodies and does not include the cleared credential linkage field.\n\n### Response notes\n- `data.mode` is `SAFE_WRITE_DB_ONLY`.\n- The response returns safe `agentDefinition` metadata and publishing clears `defaultCredentialId` internally.\n\n### Errors and retries\nA 409 can indicate a conflicting template slug. A 404 means the definition is missing or outside the authenticated organization.\n\n### Error notes\n- 409 means another template already uses the requested `templateSlug`.\n- 404 can mean the definition is missing or outside the authenticated organization.\n","tags":["Agent Builder"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agentId","in":"path","description":"Path ID for the organization-owned definition to publish."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"templateSlug":{"type":"string","minLength":1,"maxLength":120,"description":"Required stable template identifier, 1-120 characters, used for publishing and later installation."}},"required":["templateSlug"]},"example":{"templateSlug":"example-templateslug"}}},"description":"`templateSlug` is required, must be 1-120 characters, and should be stable, descriptive, and free of PHI. Publishing clears the definition credential linkage so the reusable template does not carry `defaultCredentialId`."},"responses":{"200":{"description":"Agent definition published as a template.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"agentDefinition":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string","enum":["ELIGIBILITY","CLAIMS","PAYMENTS","ENROLLMENT","PRIOR_AUTH","DENIAL","REPORTING","PATIENT","PROVIDER","BILLING","CUSTOM"]},"applicationUrl":{"type":"string"},"applicationName":{"type":"string"},"applicationType":{"type":"string","enum":["EHR","PAYER_PORTAL","CLEARINGHOUSE","GOVERNMENT","LAB","PHARMACY","REGISTRY","CUSTOM"]},"mode":{"type":"string","enum":["READ","WRITE","READ_WRITE"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","ARCHIVED"]},"version":{"type":"integer"},"requiresApproval":{"type":"boolean"},"creditCost":{"type":"integer"},"tokenBudget":{"type":"integer"},"timeoutSeconds":{"type":"integer"},"maxRetries":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","slug","description","category","applicationUrl","applicationName","applicationType","mode","status","version","requiresApproval","creditCost","tokenBudget","timeoutSeconds","maxRetries","createdAt","updatedAt"]}},"required":["mode","agentDefinition"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","agentDefinition":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example publish_agent_builder_template","slug":"example-slug","description":"Example publish_agent_builder_template note","category":"ELIGIBILITY","applicationUrl":"https://example.quickintell.com/resource","applicationName":"Example publish_agent_builder_template","applicationType":"EHR","mode":"READ","status":"DRAFT","version":1,"requiresApproval":true,"creditCost":1,"tokenBudget":1,"timeoutSeconds":1,"maxRetries":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies the action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested agent-builder resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting agent-builder resource already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/appeals":{"get":{"operationId":"listAppeals","summary":"List appeals","description":"Returns appeal summaries owned by the authenticated organization, with filters for pagination, workflow status, appeal level, denial case, claim, outcome, submission method, payer identity/name, deadline range, created range, updated range, and submitted range.\n\n### When to use\nUse this endpoint to build appeal worklists, reconcile downstream automation with QuickRCM appeal records, or find an appeal before reading details or managing documents.\n\n### Before calling\nAuthenticate with an API key that has `appeals:read` or `appeals:write`. Decide which filters keep the worklist narrow enough for operational use.\n\n### Request guidance\nUse `skip` and `take` for pagination. Narrow lists with supported filters: `status`, `level`, `denialCaseId`, `claimId`, `outcome`, `submissionMethod`, `payerId`, `payerName`, `deadlineFrom`, `deadlineTo`, `createdFrom`, `createdTo`, `updatedFrom`, `updatedTo`, `submittedFrom`, and `submittedTo`. Do not send organizationId; the API key selects the tenant.\n\n### Request notes\n- `take` is bounded by the request schema; use pagination for production lists.\n- Payer filters match QuickRCM payer configuration context rather than accepting raw payer portal credentials.\n\n### Response semantics\nThe response contains sanitized local appeal summaries plus `total`. It does not include raw denial case, patient, activity metadata, or payer payload details.\n\n### Response notes\n- Appeal amounts are serialized as decimal strings.\n- Returned records are local QuickRCM appeal workflow records.\n\n### Errors and retries\nTreat 400 as invalid filters, 401/403 as credential or scope issues, and 429 as a signal to back off before polling again.\n\n### Error notes\n- 400 means one or more filter values failed schema validation.\n- Do not retry authorization failures without changing API-key scope or credentials.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000},"required":false,"name":"skip","in":"query","description":"Zero-based pagination offset. The schema permits 0 through 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"take","in":"query","description":"Page size for appeal summaries. The schema permits 1 through 100."},{"schema":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"required":false,"name":"status","in":"query","description":"Local appeal workflow status filter using the Appeals status enum."},{"schema":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"required":false,"name":"level","in":"query","description":"Appeal level filter using the Appeals level enum."},{"schema":{"type":"string","minLength":1},"required":false,"name":"denialCaseId","in":"query","description":"QuickRCM denial case identifier used to find appeals opened from that denial."},{"schema":{"type":"string","minLength":1},"required":false,"name":"claimId","in":"query","description":"QuickRCM claim identifier used to find appeals associated with that claim."},{"schema":{"type":"string","enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"required":false,"name":"outcome","in":"query","description":"Appeal outcome filter using the Appeals outcome enum."},{"schema":{"type":"string","enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"required":false,"name":"submissionMethod","in":"query","description":"Submission channel filter such as FAX, MAIL_CERTIFIED, MAIL_REGULAR, EDI_277, PHONE_VERBAL, or ELECTRONIC_PORTAL."},{"schema":{"type":"string","minLength":1},"required":false,"name":"payerId","in":"query","description":"QuickRCM payer configuration identifier filter."},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"payerName","in":"query","description":"Payer-name filter across the appeal's denial or claim payer context."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"deadlineFrom","in":"query","description":"Lower ISO datetime bound for `appealDeadline`."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"deadlineTo","in":"query","description":"Upper ISO datetime bound for `appealDeadline`."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdFrom","in":"query","description":"Lower ISO datetime bound for appeal record creation time."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdTo","in":"query","description":"Upper ISO datetime bound for appeal record creation time."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"updatedFrom","in":"query","description":"Lower ISO datetime bound for appeal record update time."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"updatedTo","in":"query","description":"Upper ISO datetime bound for appeal record update time."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"submittedFrom","in":"query","description":"Lower ISO datetime bound for `submittedAt`."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"submittedTo","in":"query","description":"Upper ISO datetime bound for `submittedAt`."}],"responses":{"200":{"description":"Appeals list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"submissionMethod":{"type":["string","null"],"enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"totalAppealedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmationNumber":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"denialCaseSummary":{"type":["object","null"],"properties":{"caseNumber":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"payerName":{"type":["string","null"]},"denialReason":{"type":["string","null"]},"primaryCode":{"type":["string","null"]},"denialDate":{"type":["string","null"],"format":"date-time"}},"required":["caseNumber","claimNumber","payerName","denialReason","primaryCode","denialDate"]}},"required":["id","organizationId","denialCaseId","claimId","level","status","outcome","submissionMethod","appealDeadline","payerDecisionDate","totalAppealedAmount","totalRecoveredAmount","submittedAt","confirmationNumber","trackingNumber","createdAt","updatedAt","denialCaseSummary"]}},"total":{"type":"integer","minimum":0}},"required":["appeals","total"]}},"required":["success","data"]},"example":{"success":true,"data":{"appeals":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","submissionMethod":"ELECTRONIC_PORTAL","appealDeadline":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","totalAppealedAmount":"example-totalappealedamount","totalRecoveredAmount":"example-totalrecoveredamount","submittedAt":"2026-06-08T10:15:30Z","confirmationNumber":"example-confirmationnumber","trackingNumber":"example-trackingnumber","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","denialCaseSummary":{"caseNumber":"example-casenumber","claimNumber":"example-claimnumber","payerName":"Example appeal","denialReason":"example-denialreason","primaryCode":"example-primarycode","denialDate":"2026-06-08T10:15:30Z"}}],"total":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}},"post":{"operationId":"createAppeal","summary":"Create appeal","description":"Creates a first-level appeal for an existing organization-owned denial case.\n\n### When to use\nUse this when a denial is ready to enter QuickRCM appeal tracking and no active level-one appeal already exists for that denial case.\n\n### Before calling\nResolve the `denialCaseId` from QuickRCM and confirm the caller has write access to denial appeal workflows.\n\n### Request guidance\nSend only the denial case identifier. Keep supporting documents, appeal letters, and payer portal details in their dedicated workflows.\n\n### Request notes\n- `denialCaseId` must belong to the API key's organization.\n- Do not include patient details or document payloads in this request.\n\n### Response semantics\nA successful response returns the new local appeal record. The implementation initializes it as a local workflow record and may derive deadline and amount context from the denial case.\n\n### Response notes\n- The response is a local appeal record.\n- External submission is a separate action.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization denial context and 409 as an existing active level-one appeal. After a timeout, list or get appeals before retrying to avoid duplicates.\n\n### Error notes\n- 409 means an active level-one appeal already exists for the denial case.\n- 403 means the API key does not grant write access for this workflow.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"denialCaseId":{"type":"string","minLength":1,"description":"QuickRCM denial case identifier used as the source record for the new appeal."}},"required":["denialCaseId"]},"example":{"denialCaseId":"00000000-0000-4000-8000-000000000001"}}},"description":"Send only the denial case identifier. Keep supporting documents, appeal letters, and payer portal details in their dedicated workflows."},"responses":{"201":{"description":"Appeal created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"submissionMethod":{"type":["string","null"],"enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"totalAppealedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmationNumber":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"denialCaseSummary":{"type":["object","null"],"properties":{"caseNumber":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"payerName":{"type":["string","null"]},"denialReason":{"type":["string","null"]},"primaryCode":{"type":["string","null"]},"denialDate":{"type":["string","null"],"format":"date-time"}},"required":["caseNumber","claimNumber","payerName","denialReason","primaryCode","denialDate"]}},"required":["id","organizationId","denialCaseId","claimId","level","status","outcome","submissionMethod","appealDeadline","payerDecisionDate","totalAppealedAmount","totalRecoveredAmount","submittedAt","confirmationNumber","trackingNumber","createdAt","updatedAt","denialCaseSummary"]}},"required":["appeal"]}},"required":["success","data"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","submissionMethod":"ELECTRONIC_PORTAL","appealDeadline":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","totalAppealedAmount":"example-totalappealedamount","totalRecoveredAmount":"example-totalrecoveredamount","submittedAt":"2026-06-08T10:15:30Z","confirmationNumber":"example-confirmationnumber","trackingNumber":"example-trackingnumber","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","denialCaseSummary":{"caseNumber":"example-casenumber","claimNumber":"example-claimnumber","payerName":"Example appeal","denialReason":"example-denialreason","primaryCode":"example-primarycode","denialDate":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial case not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Active appeal already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/appeals/peer-to-peer":{"get":{"operationId":"listAppealPeerToPeerReviews","summary":"List peer-to-peer reviews","description":"Lists peer-to-peer review records for the authenticated organization.\n\n### When to use\nUse this to build a P2P schedule, find upcoming reviews, or filter reviews by appeal, provider, status, and date range.\n\n### Before calling\nChoose a date window and optional appeal/provider/status filters.\n\n### Request guidance\nUse `startDate` and `endDate` ISO datetimes, `status`, `appealId`, `providerUserId`, `skip`, and `take`. The list query does not accept `p2pReviewId`; use the get-by-id endpoint when you already have one.\n\n### Request notes\n- Filter by `appealId` when embedding P2P history on an appeal detail page.\n- Filter by `providerUserId` for provider-specific schedules.\n\n### Response semantics\nThe response returns local peer-to-peer review metadata and `total`; it does not imply payer attendance or call completion.\n\n### Response notes\n- Each item is a local P2P review record.\n- Outcome fields are populated after recording an outcome.\n\n### Errors and retries\nTreat invalid dates, unsupported status values, unknown query parameters in strict clients, and pagination bounds as 400-class validation issues. Back off on 429 for polling.\n\n### Error notes\n- 400 means filter validation failed.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":false,"name":"startDate","in":"query","description":"Lower ISO datetime bound for the scheduled peer-to-peer review window."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"endDate","in":"query","description":"Upper ISO datetime bound for the scheduled peer-to-peer review window."},{"schema":{"type":"string","enum":["REQUESTED","SCHEDULED","CONFIRMED","COMPLETED","CANCELLED","NO_SHOW_PAYER","NO_SHOW_PROVIDER","RESCHEDULED"]},"required":false,"name":"status","in":"query","description":"Peer-to-peer review status filter such as REQUESTED, SCHEDULED, CONFIRMED, COMPLETED, CANCELLED, NO_SHOW_PAYER, NO_SHOW_PROVIDER, or RESCHEDULED."},{"schema":{"type":"string","minLength":1},"required":false,"name":"appealId","in":"query","description":"Optional tenant-scoped local appeal identifier used to list P2P reviews for one appeal."},{"schema":{"type":"string","minLength":1},"required":false,"name":"providerUserId","in":"query","description":"QuickRCM user identifier for the provider assigned to the review."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000},"required":false,"name":"skip","in":"query","description":"Zero-based pagination offset. The schema permits 0 through 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"take","in":"query","description":"Page size. The schema permits 1 through 100."}],"responses":{"200":{"description":"Peer-to-peer reviews","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"peerToPeerReviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"appealId":{"type":"string"},"providerUserId":{"type":"string"},"providerName":{"type":"string"},"providerSpecialty":{"type":["string","null"]},"scheduledDate":{"type":["string","null"],"format":"date-time"},"scheduledTime":{"type":["string","null"]},"duration":{"type":["integer","null"]},"conferenceLink":{"type":["string","null"]},"dialInNumber":{"type":["string","null"]},"payerReviewerName":{"type":["string","null"]},"payerReviewerTitle":{"type":["string","null"]},"payerPhone":{"type":["string","null"]},"status":{"type":"string"},"outcome":{"type":["string","null"]},"outcomeNotes":{"type":["string","null"]},"callDuration":{"type":["integer","null"]},"followUpRequired":{"type":"boolean"},"followUpNotes":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","appealId","providerUserId","providerName","providerSpecialty","scheduledDate","scheduledTime","duration","conferenceLink","dialInNumber","payerReviewerName","payerReviewerTitle","payerPhone","status","outcome","outcomeNotes","callDuration","followUpRequired","followUpNotes","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0}},"required":["peerToPeerReviews","total"]}},"required":["success","data"]},"example":{"success":true,"data":{"peerToPeerReviews":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","providerUserId":"00000000-0000-4000-8000-000000000001","providerName":"Example appeal_peer_to_peer_review","providerSpecialty":"example-providerspecialty","scheduledDate":"2026-06-08T10:15:30Z","scheduledTime":"example-scheduledtime","duration":1,"conferenceLink":"example-conferencelink","dialInNumber":"example-dialinnumber","payerReviewerName":"Example appeal_peer_to_peer_review","payerReviewerTitle":"example-payerreviewertitle","payerPhone":"+15551234567","status":"active","outcome":"example-outcome","outcomeNotes":"Example appeal_peer_to_peer_review note","callDuration":1,"followUpRequired":true,"followUpNotes":"Example appeal_peer_to_peer_review note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/compliance-events":{"get":{"operationId":"listAppealComplianceEvents","summary":"List appeal compliance events","description":"Lists appeal compliance events for the authenticated organization.\n\n### When to use\nUse this to build compliance queues for missed deadlines, overdue payer responses, or state-law violation tracking.\n\n### Before calling\nChoose optional event type, appeal, resolution, date, and pagination filters.\n\n### Request guidance\nUse `eventType` values from the schema, `resolved=true|false` for queue separation, optional ISO `startDate`/`endDate` bounds for event creation time, optional `appealId` for one appeal, and `skip`/`take` for pagination.\n\n### Request notes\n- `eventType` supports APPEAL_DEADLINE_MISSED, PAYER_RESPONSE_OVERDUE, and STATE_LAW_VIOLATION.\n- Filter by `resolved=false` for active compliance work.\n- `startDate` and `endDate` filter compliance events by created time using ISO datetimes.\n- `appealId` narrows the queue to events for one tenant-scoped appeal.\n- `skip` is zero-based and `take` is capped at 100.\n\n### Response semantics\nThe response returns sanitized compliance events plus total count. Internal metadata is not exposed.\n\n### Response notes\n- Compliance event metadata is sanitized.\n- `daysVariance` indicates timing variance when available.\n\n### Errors and retries\nInvalid event types or dates return 400. Back off on 429 when polling compliance queues.\n\n### Error notes\n- 400 means filter validation failed.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":false,"name":"startDate","in":"query","description":"Optional ISO datetime lower bound for compliance events, applied to the event createdAt timestamp."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"endDate","in":"query","description":"Optional ISO datetime upper bound for compliance events, applied to the event createdAt timestamp."},{"schema":{"type":"string","enum":["APPEAL_DEADLINE_MISSED","PAYER_RESPONSE_OVERDUE","STATE_LAW_VIOLATION"]},"required":false,"name":"eventType","in":"query","description":"Compliance event category."},{"schema":{"type":"string","minLength":1},"required":false,"name":"appealId","in":"query","description":"Optional tenant-scoped appeal identifier filter for compliance events tied to one appeal."},{"schema":{"type":"boolean"},"required":false,"name":"resolved","in":"query","description":"Boolean filter for resolved versus active compliance events."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000},"required":false,"name":"skip","in":"query","description":"Zero-based pagination offset; valid range is 0 through 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"take","in":"query","description":"Page size for the compliance event list; valid range is 1 through 100."}],"responses":{"200":{"description":"Appeal compliance events","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"complianceEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"appealId":{"type":["string","null"]},"eventType":{"type":"string"},"severity":{"type":["string","null"]},"regulation":{"type":["string","null"]},"jurisdictionState":{"type":["string","null"]},"payerType":{"type":["string","null"]},"description":{"type":["string","null"]},"deadlineDate":{"type":["string","null"],"format":"date-time"},"actualDate":{"type":["string","null"],"format":"date-time"},"daysVariance":{"type":["integer","null"]},"isResolved":{"type":"boolean"},"resolvedBy":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolutionAction":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","appealId","eventType","severity","regulation","jurisdictionState","payerType","description","deadlineDate","actualDate","daysVariance","isResolved","resolvedBy","resolvedAt","resolutionAction","createdAt"]}},"total":{"type":"integer","minimum":0}},"required":["complianceEvents","total"]}},"required":["success","data"]},"example":{"success":true,"data":{"complianceEvents":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","eventType":"example-eventtype","severity":"example-severity","regulation":"example-regulation","jurisdictionState":"example-jurisdictionstate","payerType":"example-payertype","description":"Example appeal_compliance_event note","deadlineDate":"2026-06-08T10:15:30Z","actualDate":"2026-06-08T10:15:30Z","daysVariance":1,"isResolved":true,"resolvedBy":"example-resolvedby","resolvedAt":"2026-06-08T10:15:30Z","resolutionAction":"example-resolutionaction","createdAt":"2026-06-08T10:15:30Z"}],"total":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/compliance-dashboard":{"get":{"operationId":"getAppealComplianceDashboard","summary":"Get appeal compliance dashboard","description":"Returns summary appeal compliance metrics and recent events for the authenticated organization.\n\n### When to use\nUse this for compliance dashboard tiles and lightweight monitoring.\n\n### Before calling\nChoose optional start and end datetimes for the compliance event window.\n\n### Request guidance\nUse ISO datetime query parameters when filtering by period.\n\n### Request notes\n- Use this endpoint for summary metrics rather than full event review.\n- Use listAppealComplianceEvents for pagination.\n- `startDate` and `endDate` bound the compliance event window used for dashboard counts and recent event summaries.\n\n### Response semantics\nThe response includes summary totals, active/resolved counts, counts by type, and recent sanitized events.\n\n### Response notes\n- `summary.byType` is keyed by compliance event type.\n- Recent events omit internal metadata.\n\n### Errors and retries\nTreat invalid date filters as 400 and retry transient server failures with backoff.\n\n### Error notes\n- 400 means date validation failed.\n- 429 should be retried with backoff.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":false,"name":"startDate","in":"query","description":"Optional ISO datetime lower bound for the compliance event window used to calculate dashboard metrics."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"endDate","in":"query","description":"Optional ISO datetime upper bound for the compliance event window used to calculate dashboard metrics."}],"responses":{"200":{"description":"Appeal compliance dashboard","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"summary":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"active":{"type":"integer","minimum":0},"resolved":{"type":"integer","minimum":0},"byType":{"type":"object","additionalProperties":{"type":"integer","minimum":0}}},"required":["total","active","resolved","byType"],"additionalProperties":{}},"recentEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"eventType":{"type":"string"},"appealId":{"type":["string","null"]},"description":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"resolved":{"type":"boolean"},"payerName":{"type":["string","null"]}},"required":["id","eventType","appealId","description","createdAt","resolved","payerName"]}}},"required":["summary","recentEvents"]}},"required":["success","data"]},"example":{"success":true,"data":{"summary":{"total":1,"active":1,"resolved":1,"byType":{}},"recentEvents":[{"id":"00000000-0000-4000-8000-000000000001","eventType":"example-eventtype","appealId":"00000000-0000-4000-8000-000000000001","description":"Example appeal_compliance_dashboard note","createdAt":"2026-06-08T10:15:30Z","resolved":true,"payerName":"Example appeal_compliance_dashboard"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/analytics/{reportType}":{"get":{"operationId":"getAppealAnalyticsReport","summary":"Get appeal analytics report","description":"Returns a read-only appeal analytics report for a selected report type.\n\n### When to use\nUse this for appeal success, recovery, analyst performance, payer behavior, P2P success, or summary analytics.\n\n### Before calling\nChoose `reportType` and optional filters that are meaningful for that report.\n\n### Request guidance\nChoose path `reportType` from `success-rates`, `recovery-analysis`, `analyst-performance`, `payer-behavior`, `p2p-success-rates`, or `summary`. Supported query filters are `startDate`, `endDate`, `payerId`, `payerName`, `denialCategory`, `appealLevel`, `analystUserId`, `providerUserId`, `providerSpecialty`, and `periodType`; some filters only affect the matching report implementation.\n\n### Request notes\n- `appealLevel` must use an Appeals level enum.\n- `periodType` applies to summary-style analytics.\n\n### Response semantics\nThe response wraps the selected `reportType` and serialized `report` data. Report bodies are report-type-specific and intentionally not a fixed public schema yet.\n\n### Response notes\n- `report` is report-type-specific serialized data.\n- Analytics are based on local QuickRCM appeal records.\n\n### Errors and retries\nTreat invalid report types, dates, or enum filters as 400. Back off on 429 for scheduled reporting.\n\n### Error notes\n- 400 means report type or filter validation failed.\n- 429 should be retried with backoff.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["success-rates","recovery-analysis","analyst-performance","payer-behavior","p2p-success-rates","summary"]},"required":true,"name":"reportType","in":"path","description":"Path selector for the analytics report: success-rates, recovery-analysis, analyst-performance, payer-behavior, p2p-success-rates, or summary."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"startDate","in":"query","description":"Optional lower ISO datetime bound for the report period."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"endDate","in":"query","description":"Optional upper ISO datetime bound for the report period."},{"schema":{"type":"string","minLength":1},"required":false,"name":"payerId","in":"query","description":"Optional QuickRCM payer configuration identifier filter. Used by payer/recovery/success report paths where supported."},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"payerName","in":"query","description":"Optional payer-name filter. Used by P2P success report paths where supported."},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"denialCategory","in":"query","description":"Optional denial category filter for reports that operate on denial categories."},{"schema":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"required":false,"name":"appealLevel","in":"query","description":"Optional appeal level enum filter."},{"schema":{"type":"string","minLength":1},"required":false,"name":"analystUserId","in":"query","description":"Optional QuickRCM user identifier for analyst-performance filtering."},{"schema":{"type":"string","minLength":1},"required":false,"name":"providerUserId","in":"query","description":"Optional QuickRCM provider user identifier for P2P success filtering."},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"providerSpecialty","in":"query","description":"Optional provider specialty filter for P2P success reporting."},{"schema":{"type":"string","enum":["WEEKLY","MONTHLY","QUARTERLY"]},"required":false,"name":"periodType","in":"query","description":"Optional summary aggregation period: WEEKLY, MONTHLY, or QUARTERLY."}],"responses":{"200":{"description":"Appeal analytics report","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"reportType":{"type":"string","enum":["success-rates","recovery-analysis","analyst-performance","payer-behavior","p2p-success-rates","summary"]},"report":{}},"required":["reportType"]}},"required":["success","data"]},"example":{"success":true,"data":{"reportType":"success-rates","report":"example-report"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/compliance-rules":{"get":{"operationId":"listAppealComplianceRules","summary":"List appeal compliance rules","description":"Lists appeal compliance rules available to the authenticated organization, including organization-specific and global rules.\n\n### When to use\nUse this to show filing and response timing rules before setting deadlines or scanning compliance.\n\n### Before calling\nChoose optional payer type, jurisdiction state, appeal level, active status, and pagination filters.\n\n### Request guidance\nUse `payerType`, two-letter `jurisdictionState`, `appealLevel`, `isActive`, `skip`, and `take` to narrow the tenant-visible rule set. Organization-specific rules and global fallback rules can both be returned.\n\n### Request notes\n- Organization-specific rules are ordered before global fallback rules.\n- Use `appealLevel` to narrow rules to a specific appeal stage.\n- `isActive` filters active versus inactive rules; omit it to include both states.\n- `skip` is zero-based and `take` is capped at 100.\n\n### Response semantics\nThe response returns compliance rule metadata; organizationId may be null for global fallback rules.\n\n### Response notes\n- Global rules have `organizationId: null`.\n- Rule durations are numeric day/hour fields.\n\n### Errors and retries\nTreat invalid jurisdiction state length, appeal level, or pagination as 400.\n\n### Error notes\n- 400 means filter validation failed.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"payerType","in":"query","description":"Compliance rule payer category."},{"schema":{"type":"string","minLength":2,"maxLength":2},"required":false,"name":"jurisdictionState","in":"query","description":"Two-letter state or null for non-state-specific rules."},{"schema":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"required":false,"name":"appealLevel","in":"query","description":"Optional appeal stage enum filter, such as LEVEL_1_RECONSIDERATION or INDEPENDENT_REVIEW_ORG."},{"schema":{"type":"boolean"},"required":false,"name":"isActive","in":"query","description":"Optional boolean filter for active versus inactive compliance rules; omit to include both."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000},"required":false,"name":"skip","in":"query","description":"Zero-based pagination offset for compliance rules; valid range is 0 through 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"take","in":"query","description":"Page size for compliance rules; valid range is 1 through 100."}],"responses":{"200":{"description":"Compliance rules","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"complianceRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":["string","null"]},"payerType":{"type":"string"},"jurisdictionState":{"type":["string","null"]},"appealLevel":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"providerFilingDays":{"type":"integer"},"expeditedFilingHours":{"type":["integer","null"]},"payerResponseDays":{"type":"integer"},"expeditedResponseHours":{"type":["integer","null"]},"regulatoryReference":{"type":"string"},"description":{"type":["string","null"]},"penaltyForViolation":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","payerType","jurisdictionState","appealLevel","providerFilingDays","expeditedFilingHours","payerResponseDays","expeditedResponseHours","regulatoryReference","description","penaltyForViolation","isActive","createdAt","updatedAt"]}}},"required":["complianceRules"]}},"required":["success","data"]},"example":{"success":true,"data":{"complianceRules":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","payerType":"example-payertype","jurisdictionState":"example-jurisdictionstate","appealLevel":"LEVEL_1_RECONSIDERATION","providerFilingDays":1,"expeditedFilingHours":1,"payerResponseDays":1,"expeditedResponseHours":1,"regulatoryReference":"example-regulatoryreference","description":"Example appeal_compliance_rule note","penaltyForViolation":"example-penaltyforviolation","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}},"post":{"operationId":"upsertAppealComplianceRule","summary":"Create or update appeal compliance rule","description":"Creates or updates an organization-scoped appeal compliance rule using payer type, jurisdiction state, and appeal level.\n\n### When to use\nUse this when an organization needs to define or revise its own appeal compliance timing rule.\n\n### Before calling\nConfirm the rule values match the organization's policy and have been reviewed by qualified staff; do not present these public API docs as legal advice.\n\n### Request guidance\nSend the complete rule body: required `payerType`, `appealLevel`, `providerFilingDays`, `payerResponseDays`, and `regulatoryReference`; optional `jurisdictionState`, `expeditedFilingHours`, `expeditedResponseHours`, `description`, `penaltyForViolation`, and `isActive`.\n\n### Request notes\n- `regulatoryReference` is required.\n- Set `isActive` false rather than deleting historical rule context when applicable.\n\n### Response semantics\nThe response returns the created or updated organization-scoped rule. POST can return 201 for create or 200 when an existing matching rule is updated.\n\n### Response notes\n- Returned rule is scoped to the authenticated organization.\n- Global rules are not modified by this endpoint.\n\n### Errors and retries\nAfter a timeout, list rules using the same payer type, jurisdiction state, and appeal level before retrying.\n\n### Error notes\n- 400 means rule validation failed.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payerType":{"type":"string","minLength":1,"maxLength":100,"description":"Required payer category for the compliance rule, such as a configured payer class or payer type string."},"jurisdictionState":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"Optional nullable two-letter state code for state-specific rules; null or omitted means not state-specific."},"appealLevel":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"],"description":"Required appeal level enum value the rule applies to."},"providerFilingDays":{"type":["integer","null"],"minimum":0,"maximum":3650,"description":"Required provider filing window in whole days; the schema permits 0 through 3650."},"expeditedFilingHours":{"type":["integer","null"],"minimum":0,"maximum":8760,"description":"Optional nullable expedited filing window in hours; the schema permits 0 through 8760."},"payerResponseDays":{"type":["integer","null"],"minimum":0,"maximum":3650,"description":"Required payer response window in whole days; the schema permits 0 through 3650."},"expeditedResponseHours":{"type":["integer","null"],"minimum":0,"maximum":8760,"description":"Optional nullable expedited payer response window in hours; the schema permits 0 through 8760."},"regulatoryReference":{"type":"string","minLength":1,"maxLength":500,"description":"Required reference text for the policy, contract, or regulation supporting the rule; max length is 500."},"description":{"type":["string","null"],"minLength":1,"maxLength":2000,"description":"Optional nullable rule description; max length is 2000. This is operational documentation, not legal advice."},"penaltyForViolation":{"type":["string","null"],"minLength":1,"maxLength":2000,"description":"Optional nullable description of consequence or policy for violating the rule; max length is 2000."},"isActive":{"type":"boolean","description":"Optional boolean controlling whether the rule is active."}},"required":["payerType","appealLevel","providerFilingDays","payerResponseDays","regulatoryReference"]},"example":{"payerType":"example-payertype","appealLevel":"LEVEL_1_RECONSIDERATION","providerFilingDays":1,"payerResponseDays":1,"regulatoryReference":"example-regulatoryreference","jurisdictionState":"example-jurisdictionstate","expeditedFilingHours":1,"expeditedResponseHours":1,"description":"Example upsert_appeal_compliance_rule note","penaltyForViolation":"example-penaltyforviolation","isActive":true}}},"description":"Send the complete rule body: required `payerType`, `appealLevel`, `providerFilingDays`, `payerResponseDays`, and `regulatoryReference`; optional `jurisdictionState`, `expeditedFilingHours`, `expeditedResponseHours`, `description`, `penaltyForViolation`, and `isActive`."},"responses":{"200":{"description":"Compliance rule updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"complianceRule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":["string","null"]},"payerType":{"type":"string"},"jurisdictionState":{"type":["string","null"]},"appealLevel":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"providerFilingDays":{"type":"integer"},"expeditedFilingHours":{"type":["integer","null"]},"payerResponseDays":{"type":"integer"},"expeditedResponseHours":{"type":["integer","null"]},"regulatoryReference":{"type":"string"},"description":{"type":["string","null"]},"penaltyForViolation":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","payerType","jurisdictionState","appealLevel","providerFilingDays","expeditedFilingHours","payerResponseDays","expeditedResponseHours","regulatoryReference","description","penaltyForViolation","isActive","createdAt","updatedAt"]}},"required":["complianceRule"]}},"required":["success","data"]},"example":{"success":true,"data":{"complianceRule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","payerType":"example-payertype","jurisdictionState":"example-jurisdictionstate","appealLevel":"LEVEL_1_RECONSIDERATION","providerFilingDays":1,"expeditedFilingHours":1,"payerResponseDays":1,"expeditedResponseHours":1,"regulatoryReference":"example-regulatoryreference","description":"Example upsert_appeal_compliance_rule note","penaltyForViolation":"example-penaltyforviolation","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"201":{"description":"Compliance rule created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"complianceRule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":["string","null"]},"payerType":{"type":"string"},"jurisdictionState":{"type":["string","null"]},"appealLevel":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"providerFilingDays":{"type":"integer"},"expeditedFilingHours":{"type":["integer","null"]},"payerResponseDays":{"type":"integer"},"expeditedResponseHours":{"type":["integer","null"]},"regulatoryReference":{"type":"string"},"description":{"type":["string","null"]},"penaltyForViolation":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","payerType","jurisdictionState","appealLevel","providerFilingDays","expeditedFilingHours","payerResponseDays","expeditedResponseHours","regulatoryReference","description","penaltyForViolation","isActive","createdAt","updatedAt"]}},"required":["complianceRule"]}},"required":["success","data"]},"example":{"success":true,"data":{"complianceRule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","payerType":"example-payertype","jurisdictionState":"example-jurisdictionstate","appealLevel":"LEVEL_1_RECONSIDERATION","providerFilingDays":1,"expeditedFilingHours":1,"payerResponseDays":1,"expeditedResponseHours":1,"regulatoryReference":"example-regulatoryreference","description":"Example upsert_appeal_compliance_rule note","penaltyForViolation":"example-penaltyforviolation","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/compliance-rules/{ruleId}":{"put":{"operationId":"upsertAppealComplianceRuleById","summary":"Update appeal compliance rule by id","description":"Updates an organization-scoped appeal compliance rule by rule id.\n\n### When to use\nUse this when the caller already knows the exact rule to revise.\n\n### Before calling\nRead the rule and confirm it belongs to the authenticated organization. The PUT request is a complete rule payload, not a partial patch.\n\n### Request guidance\nPass `ruleId` in the path and send the same complete rule body used by upsertAppealComplianceRule: required `payerType`, `appealLevel`, `providerFilingDays`, `payerResponseDays`, and `regulatoryReference`; optional `jurisdictionState`, `expeditedFilingHours`, `expeditedResponseHours`, `description`, `penaltyForViolation`, and `isActive`.\n\n### Request notes\n- `ruleId` selects the existing organization-specific rule.\n- Use the POST upsert endpoint when identifying a rule by payer type, jurisdiction, and level instead.\n\n### Response semantics\nThe response returns the updated organization-scoped compliance rule.\n\n### Response notes\n- Returns the updated compliance rule.\n- The request uses PUT semantics with a complete rule payload.\n\n### Errors and retries\n404 means the rule does not exist for the organization. After a timeout, read/list rules before retrying.\n\n### Error notes\n- 404 means the rule id is missing or not owned by the organization.\n- 400 means body validation failed.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ruleId","in":"path","description":"Tenant-scoped QuickRCM appeal compliance rule identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payerType":{"type":"string","minLength":1,"maxLength":100,"description":"Required payer category for the compliance rule, such as a configured payer class or payer type string."},"jurisdictionState":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"Optional nullable two-letter state code for state-specific rules; null or omitted means not state-specific."},"appealLevel":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"],"description":"Required appeal level enum value the rule applies to."},"providerFilingDays":{"type":["integer","null"],"minimum":0,"maximum":3650,"description":"Required provider filing window in whole days; the schema permits 0 through 3650."},"expeditedFilingHours":{"type":["integer","null"],"minimum":0,"maximum":8760,"description":"Optional nullable expedited filing window in hours; the schema permits 0 through 8760."},"payerResponseDays":{"type":["integer","null"],"minimum":0,"maximum":3650,"description":"Required payer response window in whole days; the schema permits 0 through 3650."},"expeditedResponseHours":{"type":["integer","null"],"minimum":0,"maximum":8760,"description":"Optional nullable expedited payer response window in hours; the schema permits 0 through 8760."},"regulatoryReference":{"type":"string","minLength":1,"maxLength":500,"description":"Required reference text for the policy, contract, or regulation supporting the rule; max length is 500."},"description":{"type":["string","null"],"minLength":1,"maxLength":2000,"description":"Optional nullable rule description; max length is 2000. This is operational documentation, not legal advice."},"penaltyForViolation":{"type":["string","null"],"minLength":1,"maxLength":2000,"description":"Optional nullable description of consequence or policy for violating the rule; max length is 2000."},"isActive":{"type":"boolean","description":"Optional boolean controlling whether the rule is active."}},"required":["payerType","appealLevel","providerFilingDays","payerResponseDays","regulatoryReference"]},"example":{"payerType":"example-payertype","appealLevel":"LEVEL_1_RECONSIDERATION","providerFilingDays":1,"payerResponseDays":1,"regulatoryReference":"example-regulatoryreference","jurisdictionState":"example-jurisdictionstate","expeditedFilingHours":1,"expeditedResponseHours":1,"description":"Example upsert_appeal_compliance_rule_by_id note","penaltyForViolation":"example-penaltyforviolation","isActive":true}}},"description":"Pass `ruleId` in the path and send the same complete rule body used by upsertAppealComplianceRule: required `payerType`, `appealLevel`, `providerFilingDays`, `payerResponseDays`, and `regulatoryReference`; optional `jurisdictionState`, `expeditedFilingHours`, `expeditedResponseHours`, `description`, `penaltyForViolation`, and `isActive`."},"responses":{"200":{"description":"Compliance rule updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"complianceRule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":["string","null"]},"payerType":{"type":"string"},"jurisdictionState":{"type":["string","null"]},"appealLevel":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"providerFilingDays":{"type":"integer"},"expeditedFilingHours":{"type":["integer","null"]},"payerResponseDays":{"type":"integer"},"expeditedResponseHours":{"type":["integer","null"]},"regulatoryReference":{"type":"string"},"description":{"type":["string","null"]},"penaltyForViolation":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","payerType","jurisdictionState","appealLevel","providerFilingDays","expeditedFilingHours","payerResponseDays","expeditedResponseHours","regulatoryReference","description","penaltyForViolation","isActive","createdAt","updatedAt"]}},"required":["complianceRule"]}},"required":["success","data"]},"example":{"success":true,"data":{"complianceRule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","payerType":"example-payertype","jurisdictionState":"example-jurisdictionstate","appealLevel":"LEVEL_1_RECONSIDERATION","providerFilingDays":1,"expeditedFilingHours":1,"payerResponseDays":1,"expeditedResponseHours":1,"regulatoryReference":"example-regulatoryreference","description":"Example upsert_appeal_compliance_rule_by_id note","penaltyForViolation":"example-penaltyforviolation","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Compliance rule not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/calendar":{"get":{"operationId":"getAppealCalendar","summary":"Get appeal calendar","description":"Returns appeal calendar event data for deadlines and peer-to-peer reviews within a date range.\n\n### When to use\nUse this to build calendar views or operational planning screens for appeal deadlines and P2P reviews.\n\n### Before calling\nProvide a valid ISO datetime `startDate` and `endDate` where start is before end.\n\n### Request guidance\nKeep the date range focused; wide ranges can create large calendar payloads.\n\n### Request notes\n- `startDate` and `endDate` are required.\n- Use ISO datetimes to avoid timezone ambiguity.\n- `startDate` is the required ISO datetime lower bound for returned calendar events.\n- `endDate` is the required ISO datetime upper bound for returned calendar events.\n\n### Response semantics\nCurrent implementation returns calendar data with top-level `days`, `totalEvents`, `overdueCount`, and `dueSoonCount`. `days` contains only dates that have deadline or peer-to-peer events. The OpenAPI response schema remains generic.\n\n### Response notes\n- Only dates with events may be returned.\n- Calendar events are local QuickRCM workflow events.\n\n### Errors and retries\n400 means invalid or reversed date range. Retry transient server failures with backoff.\n\n### Error notes\n- 400 means date validation failed.\n- 429 should be retried with backoff.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":true,"name":"startDate","in":"query","description":"Required ISO datetime lower bound for the calendar range; must be before `endDate`."},{"schema":{"type":"string","format":"date-time"},"required":true,"name":"endDate","in":"query","description":"Required ISO datetime upper bound for the calendar range; must be after `startDate`."}],"responses":{"200":{"description":"Appeal calendar","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"]},"example":{"success":true,"data":"example-data"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/templates/library":{"get":{"operationId":"getSystemTemplateLibrary","summary":"List system appeal templates","description":"Lists global payer-specific appeal templates available to the authenticated organization.","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"payerName","in":"query"},{"schema":{"type":"string","enum":["HTML","MARKDOWN","PDF_FORM_MAPPING"]},"required":false,"name":"templateFormat","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000},"required":false,"name":"skip","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"take","in":"query"}],"responses":{"200":{"description":"System template library","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":["string","null"]},"templateName":{"type":"string"},"description":{"type":["string","null"]},"payerName":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerType":{"type":["string","null"]},"templateFormat":{"type":"string","enum":["HTML","MARKDOWN","PDF_FORM_MAPPING"]},"content":{"type":"string"},"metadata":{},"requiredDocuments":{"type":"array","items":{"type":"string","enum":["APPEAL_LETTER","CLINICAL_NOTES","OPERATIVE_REPORT","PATHOLOGY_REPORT","RADIOLOGY_REPORT","LAB_RESULTS","PRIOR_AUTHORIZATION","REFERRAL","MEDICAL_RECORDS","LETTER_OF_MEDICAL_NECESSITY","PEER_REVIEWED_LITERATURE","CLINICAL_GUIDELINES","PAYER_POLICY_EXCERPT","CONTRACT_EXCERPT","PHYSICIAN_ATTESTATION","PATIENT_CONSENT","CORRECTED_CLAIM_FORM","ITEMIZED_BILL","EOB_REMITTANCE","PAYER_DENIAL_LETTER","PAYER_RESPONSE","OTHER"]}},"isSystemTemplate":{"type":"boolean"},"isActive":{"type":"boolean"},"version":{"type":"integer"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","templateName","description","payerName","payerId","payerType","templateFormat","content","requiredDocuments","isSystemTemplate","isActive","version","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0}},"required":["templates","total"]}},"required":["success","data"]},"example":{"success":true,"data":{"templates":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","templateName":"Example system_template_library","description":"Example system_template_library note","payerName":"Example system_template_library","payerId":"87726","payerType":"example-payertype","templateFormat":"HTML","content":"example-content","requiredDocuments":["APPEAL_LETTER"],"isSystemTemplate":true,"isActive":true,"version":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","metadata":"example-metadata"}],"total":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/templates/for-payer":{"get":{"operationId":"getTemplateForPayer","summary":"Get appeal template for payer","description":"Returns the best system appeal template for a payer, falling back to the generic commercial template.","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"payerName","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"payerId","in":"query"}],"responses":{"200":{"description":"Payer template","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":["string","null"]},"templateName":{"type":"string"},"description":{"type":["string","null"]},"payerName":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerType":{"type":["string","null"]},"templateFormat":{"type":"string","enum":["HTML","MARKDOWN","PDF_FORM_MAPPING"]},"content":{"type":"string"},"metadata":{},"requiredDocuments":{"type":"array","items":{"type":"string","enum":["APPEAL_LETTER","CLINICAL_NOTES","OPERATIVE_REPORT","PATHOLOGY_REPORT","RADIOLOGY_REPORT","LAB_RESULTS","PRIOR_AUTHORIZATION","REFERRAL","MEDICAL_RECORDS","LETTER_OF_MEDICAL_NECESSITY","PEER_REVIEWED_LITERATURE","CLINICAL_GUIDELINES","PAYER_POLICY_EXCERPT","CONTRACT_EXCERPT","PHYSICIAN_ATTESTATION","PATIENT_CONSENT","CORRECTED_CLAIM_FORM","ITEMIZED_BILL","EOB_REMITTANCE","PAYER_DENIAL_LETTER","PAYER_RESPONSE","OTHER"]}},"isSystemTemplate":{"type":"boolean"},"isActive":{"type":"boolean"},"version":{"type":"integer"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","templateName","description","payerName","payerId","payerType","templateFormat","content","requiredDocuments","isSystemTemplate","isActive","version","createdAt","updatedAt"]}},"required":["template"]}},"required":["success","data"]},"example":{"success":true,"data":{"template":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","templateName":"Example template_for_payer","description":"Example template_for_payer note","payerName":"Example template_for_payer","payerId":"87726","payerType":"example-payertype","templateFormat":"HTML","content":"example-content","requiredDocuments":["APPEAL_LETTER"],"isSystemTemplate":true,"isActive":true,"version":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","metadata":"example-metadata"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/templates/{templateId}/duplicate":{"post":{"operationId":"duplicateTemplateToOrg","summary":"Duplicate system appeal template","description":"Copies a system appeal template into the authenticated organization for customization.","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"templateId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"templateName":{"type":"string","minLength":1,"maxLength":255}}},"example":{"templateName":"Example duplicate_template_to_org"}}}},"responses":{"200":{"description":"Duplicated template","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":["string","null"]},"templateName":{"type":"string"},"description":{"type":["string","null"]},"payerName":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerType":{"type":["string","null"]},"templateFormat":{"type":"string","enum":["HTML","MARKDOWN","PDF_FORM_MAPPING"]},"content":{"type":"string"},"metadata":{},"requiredDocuments":{"type":"array","items":{"type":"string","enum":["APPEAL_LETTER","CLINICAL_NOTES","OPERATIVE_REPORT","PATHOLOGY_REPORT","RADIOLOGY_REPORT","LAB_RESULTS","PRIOR_AUTHORIZATION","REFERRAL","MEDICAL_RECORDS","LETTER_OF_MEDICAL_NECESSITY","PEER_REVIEWED_LITERATURE","CLINICAL_GUIDELINES","PAYER_POLICY_EXCERPT","CONTRACT_EXCERPT","PHYSICIAN_ATTESTATION","PATIENT_CONSENT","CORRECTED_CLAIM_FORM","ITEMIZED_BILL","EOB_REMITTANCE","PAYER_DENIAL_LETTER","PAYER_RESPONSE","OTHER"]}},"isSystemTemplate":{"type":"boolean"},"isActive":{"type":"boolean"},"version":{"type":"integer"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","templateName","description","payerName","payerId","payerType","templateFormat","content","requiredDocuments","isSystemTemplate","isActive","version","createdAt","updatedAt"]}},"required":["template"]}},"required":["success","data"]},"example":{"success":true,"data":{"template":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","templateName":"Example duplicate_template_to_org","description":"Example duplicate_template_to_org note","payerName":"Example duplicate_template_to_org","payerId":"87726","payerType":"example-payertype","templateFormat":"HTML","content":"example-content","requiredDocuments":["APPEAL_LETTER"],"isSystemTemplate":true,"isActive":true,"version":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","metadata":"example-metadata"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/{appealId}":{"get":{"operationId":"getAppeal","summary":"Get appeal","description":"Returns one organization-owned appeal and can include a sanitized timeline and escalation chain.\n\n### When to use\nUse this after a list response, workflow event, or user selection provides an `appealId`.\n\n### Before calling\nConfirm the `appealId` came from the same tenant context as the bearer API key.\n\n### Request guidance\nUse `includeTimeline=true` only when activity history is needed. Use `includeEscalationChain=true` when you need prior or next-level appeal context for the same denial case.\n\n### Request notes\n- The path `appealId` selects the local appeal.\n- Boolean query values may be sent as `true` or `false` strings.\n\n### Response semantics\nThe core appeal object is sanitized. Optional timeline entries omit PHI-heavy descriptions and metadata; optional escalation chain entries expose appeal-stage state only.\n\n### Response notes\n- Timeline data is intentionally sanitized.\n- Escalation chain items are local QuickRCM appeal records for the same denial case.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization appeal context. Retry transient 5xx responses with backoff.\n\n### Error notes\n- 404 can mean the appeal does not exist or does not belong to the authenticated organization.\n- Do not retry 400 without correcting query values.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."},{"schema":{"type":"boolean"},"required":false,"name":"includeTimeline","in":"query","description":"When true, includes sanitized appeal activity fields."},{"schema":{"type":"boolean"},"required":false,"name":"includeEscalationChain","in":"query","description":"When true, includes appeal records for the same denial case ordered as an escalation chain."}],"responses":{"200":{"description":"Appeal","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"submissionMethod":{"type":["string","null"],"enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"totalAppealedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmationNumber":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"denialCaseSummary":{"type":["object","null"],"properties":{"caseNumber":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"payerName":{"type":["string","null"]},"denialReason":{"type":["string","null"]},"primaryCode":{"type":["string","null"]},"denialDate":{"type":["string","null"],"format":"date-time"}},"required":["caseNumber","claimNumber","payerName","denialReason","primaryCode","denialDate"]}},"required":["id","organizationId","denialCaseId","claimId","level","status","outcome","submissionMethod","appealDeadline","payerDecisionDate","totalAppealedAmount","totalRecoveredAmount","submittedAt","confirmationNumber","trackingNumber","createdAt","updatedAt","denialCaseSummary"]},"timeline":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"appealId":{"type":"string"},"activityType":{"type":"string"},"previousValue":{"type":["string","null"]},"newValue":{"type":["string","null"]},"performedBy":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"}},"required":["id","appealId","activityType","previousValue","newValue","performedBy","createdAt"]}},"escalationChain":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"previousAppealId":{"type":["string","null"]},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","previousAppealId","denialCaseId","claimId","level","status","outcome","appealDeadline","submittedAt","payerDecisionDate","createdAt","updatedAt"]}}},"required":["appeal"]}},"required":["success","data"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","submissionMethod":"ELECTRONIC_PORTAL","appealDeadline":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","totalAppealedAmount":"example-totalappealedamount","totalRecoveredAmount":"example-totalrecoveredamount","submittedAt":"2026-06-08T10:15:30Z","confirmationNumber":"example-confirmationnumber","trackingNumber":"example-trackingnumber","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","denialCaseSummary":{"caseNumber":"example-casenumber","claimNumber":"example-claimnumber","payerName":"Example appeal","denialReason":"example-denialreason","primaryCode":"example-primarycode","denialDate":"2026-06-08T10:15:30Z"}},"timeline":[{"id":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","activityType":"example-activitytype","previousValue":"example-previousvalue","newValue":"example-newvalue","performedBy":"example-performedby","createdAt":"2026-06-08T10:15:30Z"}],"escalationChain":[{"id":"00000000-0000-4000-8000-000000000001","previousAppealId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","appealDeadline":"2026-06-08T10:15:30Z","submittedAt":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/{appealId}/submit":{"post":{"operationId":"submitAppeal","summary":"Submit appeal","description":"Submits or validates a local appeal workflow using the selected submission method.\n\n### When to use\nUse this after required supporting documents are ready and the appeal should move into a submitted or validated submission state.\n\n### Before calling\nConfirm the appeal belongs to the authenticated organization and that required supporting documents have been reviewed and approved when the workflow requires it.\n\n### Request guidance\nFor fax, mail, EDI, phone, and similar local methods, send `submissionMethod` and an optional `confirmationNumber`. For `ELECTRONIC_PORTAL`, send `validateOnly: true`; public API electronic portal submission is validation-only.\n\n### Request notes\n- `queueOnly` is accepted by the schema as reserved future workflow metadata but is not current payer submission behavior.\n- Use `confirmationNumber` only when the confirmation is known and supportable.\n\n### Response semantics\nNon-electronic methods return the updated local appeal. Electronic portal validation returns `status: VALIDATED_ONLY` and `externalSubmission: SIMULATED_ONLY`; it is not payer transmission evidence.\n\n### Response notes\n- A successful response does not by itself prove payer acceptance.\n- Electronic portal validation returns a simulated validation result.\n\n### Errors and retries\nFix validation or workflow-state errors before retrying. Back off on 429. After timeouts, read the appeal before retrying a submission action.\n\n### Error notes\n- 400 can indicate invalid workflow state, missing approved documents, or electronic portal requests without validateOnly.\n- 409-style workflow conflicts should be handled by re-reading appeal state before retrying.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"submissionMethod":{"type":"string","enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"],"description":"Appeal submission channel such as FAX, MAIL_CERTIFIED, MAIL_REGULAR, EDI_277, PHONE_VERBAL, or ELECTRONIC_PORTAL."},"confirmationNumber":{"type":"string","minLength":1,"maxLength":255,"description":"Confirmation captured from the submission channel. Do not place credentials or raw payer payloads here."},"validateOnly":{"type":"boolean","description":"Required for public API ELECTRONIC_PORTAL requests; validates local access without external payer submission."},"queueOnly":{"type":"boolean","description":"Reserved for a future queued electronic submission workflow."}},"required":["submissionMethod"]},"example":{"submissionMethod":"ELECTRONIC_PORTAL","confirmationNumber":"example-confirmationnumber","validateOnly":true,"queueOnly":true}}},"description":"For fax, mail, EDI, phone, and similar local methods, send `submissionMethod` and an optional `confirmationNumber`. For `ELECTRONIC_PORTAL`, send `validateOnly: true`; public API electronic portal submission is validation-only."},"responses":{"200":{"description":"Appeal submitted or validated","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"submissionMethod":{"type":["string","null"],"enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"totalAppealedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmationNumber":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"denialCaseSummary":{"type":["object","null"],"properties":{"caseNumber":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"payerName":{"type":["string","null"]},"denialReason":{"type":["string","null"]},"primaryCode":{"type":["string","null"]},"denialDate":{"type":["string","null"],"format":"date-time"}},"required":["caseNumber","claimNumber","payerName","denialReason","primaryCode","denialDate"]}},"required":["id","organizationId","denialCaseId","claimId","level","status","outcome","submissionMethod","appealDeadline","payerDecisionDate","totalAppealedAmount","totalRecoveredAmount","submittedAt","confirmationNumber","trackingNumber","createdAt","updatedAt","denialCaseSummary"]}},"required":["appeal"]}},"required":["success","data"]},{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appealId":{"type":"string"},"status":{"type":"string","enum":["VALIDATED_ONLY"]},"externalSubmission":{"type":"string","enum":["SIMULATED_ONLY"]}},"required":["appealId","status","externalSubmission"]}},"required":["success","data"]}]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","submissionMethod":"ELECTRONIC_PORTAL","appealDeadline":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","totalAppealedAmount":"example-totalappealedamount","totalRecoveredAmount":"example-totalrecoveredamount","submittedAt":"2026-06-08T10:15:30Z","confirmationNumber":"example-confirmationnumber","trackingNumber":"example-trackingnumber","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","denialCaseSummary":{"caseNumber":"example-casenumber","claimNumber":"example-claimnumber","payerName":"Example appeal","denialReason":"example-denialreason","primaryCode":"example-primarycode","denialDate":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/{appealId}/status":{"put":{"operationId":"updateAppealStatus","summary":"Update appeal status","description":"Updates an appeal's workflow status through the module state machine.\n\n### When to use\nUse this when a payer acknowledgment, review step, documentation request, or internal workflow action changes appeal status.\n\n### Before calling\nRead the current appeal state and choose a valid target status from the Appeals schema.\n\n### Request guidance\nSend the target `status` and an optional concise `note`. Keep notes free of credentials, raw payer payloads, and unnecessary PHI.\n\n### Request notes\n- Use only statuses listed in the Appeals OpenAPI schema.\n- Do not use status updates to store raw vendor response bodies.\n\n### Response semantics\nThe response returns the updated local appeal. It does not create a payer acknowledgment unless the status change is backed by your workflow evidence.\n\n### Response notes\n- The returned appeal reflects local workflow state.\n- Amounts and dates are serialized for public API use.\n\n### Errors and retries\nTreat invalid transitions or invalid enum values as non-retryable 400s. Re-read appeal state after 409 conflicts.\n\n### Error notes\n- 400 can mean the status enum or transition is invalid.\n- 409 means the appeal changed between read and write.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"],"description":"Target appeal workflow status."},"note":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional short staff note for the status change."}},"required":["status"]},"example":{"status":"DRAFT","note":"Example appeal_statu note"}}},"description":"Send the target `status` and an optional concise `note`. Keep notes free of credentials, raw payer payloads, and unnecessary PHI."},"responses":{"200":{"description":"Appeal status updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"submissionMethod":{"type":["string","null"],"enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"totalAppealedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmationNumber":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"denialCaseSummary":{"type":["object","null"],"properties":{"caseNumber":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"payerName":{"type":["string","null"]},"denialReason":{"type":["string","null"]},"primaryCode":{"type":["string","null"]},"denialDate":{"type":["string","null"],"format":"date-time"}},"required":["caseNumber","claimNumber","payerName","denialReason","primaryCode","denialDate"]}},"required":["id","organizationId","denialCaseId","claimId","level","status","outcome","submissionMethod","appealDeadline","payerDecisionDate","totalAppealedAmount","totalRecoveredAmount","submittedAt","confirmationNumber","trackingNumber","createdAt","updatedAt","denialCaseSummary"]}},"required":["appeal"]}},"required":["success","data"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","submissionMethod":"ELECTRONIC_PORTAL","appealDeadline":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","totalAppealedAmount":"example-totalappealedamount","totalRecoveredAmount":"example-totalrecoveredamount","submittedAt":"2026-06-08T10:15:30Z","confirmationNumber":"example-confirmationnumber","trackingNumber":"example-trackingnumber","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","denialCaseSummary":{"caseNumber":"example-casenumber","claimNumber":"example-claimnumber","payerName":"Example appeal_statu","denialReason":"example-denialreason","primaryCode":"example-primarycode","denialDate":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Concurrent status update conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/appeals/{appealId}/escalate":{"post":{"operationId":"escalateAppeal","summary":"Escalate appeal","description":"Creates or returns the next-level appeal when the current appeal is eligible for escalation.\n\n### When to use\nUse this after an appeal outcome or workflow event requires moving to a formal next-level review.\n\n### Before calling\nConfirm the current appeal is in a state that can be escalated and that the caller has write scope.\n\n### Request guidance\nPass the current `appealId` and optional `note` explaining the escalation basis. Keep detailed documents in the supporting-document workflow.\n\n### Request notes\n- Use `getAppeal` with `includeEscalationChain=true` to inspect related appeal levels.\n- Escalation does not submit the new appeal externally.\n\n### Response semantics\nThe response is the resulting local appeal record for the next stage of the denial appeal workflow.\n\n### Response notes\n- The returned appeal may have a new appeal id and level.\n- The prior appeal remains part of the escalation chain.\n\n### Errors and retries\nTreat invalid state or missing source appeal as requiring operator review. Re-read the appeal chain before retrying after a timeout.\n\n### Error notes\n- 404 means the source appeal is missing or inaccessible.\n- 400 can indicate an ineligible workflow state.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional internal reason for escalation."}}},"example":{"note":"Example escalate_appeal note"}}},"description":"Pass the current `appealId` and optional `note` explaining the escalation basis. Keep detailed documents in the supporting-document workflow."},"responses":{"200":{"description":"Appeal escalated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"submissionMethod":{"type":["string","null"],"enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"totalAppealedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmationNumber":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"denialCaseSummary":{"type":["object","null"],"properties":{"caseNumber":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"payerName":{"type":["string","null"]},"denialReason":{"type":["string","null"]},"primaryCode":{"type":["string","null"]},"denialDate":{"type":["string","null"],"format":"date-time"}},"required":["caseNumber","claimNumber","payerName","denialReason","primaryCode","denialDate"]}},"required":["id","organizationId","denialCaseId","claimId","level","status","outcome","submissionMethod","appealDeadline","payerDecisionDate","totalAppealedAmount","totalRecoveredAmount","submittedAt","confirmationNumber","trackingNumber","createdAt","updatedAt","denialCaseSummary"]}},"required":["appeal"]}},"required":["success","data"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","submissionMethod":"ELECTRONIC_PORTAL","appealDeadline":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","totalAppealedAmount":"example-totalappealedamount","totalRecoveredAmount":"example-totalrecoveredamount","submittedAt":"2026-06-08T10:15:30Z","confirmationNumber":"example-confirmationnumber","trackingNumber":"example-trackingnumber","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","denialCaseSummary":{"caseNumber":"example-casenumber","claimNumber":"example-claimnumber","payerName":"Example escalate_appeal","denialReason":"example-denialreason","primaryCode":"example-primarycode","denialDate":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/{appealId}/outcome":{"post":{"operationId":"recordAppealOutcome","summary":"Record appeal outcome","description":"Records the payer or review outcome for an appeal and optionally captures recovered amount and notes.\n\n### When to use\nUse this when a final or partial appeal decision has been received and the local appeal should reflect the result.\n\n### Before calling\nConfirm the outcome is supported by a payer response, review decision, or documented settlement.\n\n### Request guidance\nSend a valid `outcome`, optional non-negative `recoveredAmount`, and concise `note`. Do not use this endpoint to post payments or store remittance payloads.\n\n### Request notes\n- `recoveredAmount` should reflect confirmed recovery only.\n- Use outcome values from the Appeals schema.\n\n### Response semantics\nThe response updates local appeal outcome and recovery reporting context. Cash posting and ERA reconciliation are separate workflows.\n\n### Response notes\n- The updated appeal includes `outcome` and recovered amount fields.\n- Payment posting is not performed by this endpoint.\n\n### Errors and retries\nAfter a timeout, re-read the appeal before retrying to avoid duplicate notes or stale outcome writes.\n\n### Error notes\n- 400 means outcome or amount failed validation.\n- 409 means the appeal changed during the update.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"],"description":"Appeal result such as FULL_OVERTURN, PARTIAL_OVERTURN, UPHELD, DISMISSED_PROCEDURAL, WITHDRAWN_BY_PROVIDER, SETTLED, or NO_RESPONSE_DEFAULT."},"recoveredAmount":{"type":["number","null"],"minimum":0,"description":"Non-negative amount recovered through the appeal decision."},"note":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional note for the recorded appeal outcome. Do not store remittance payloads or raw payer responses here."}},"required":["outcome"]},"example":{"outcome":"FULL_OVERTURN","recoveredAmount":125.5,"note":"Example appeal_outcome note"}}},"description":"Send a valid `outcome`, optional non-negative `recoveredAmount`, and concise `note`. Do not use this endpoint to post payments or store remittance payloads."},"responses":{"200":{"description":"Appeal outcome recorded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"submissionMethod":{"type":["string","null"],"enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"totalAppealedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmationNumber":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"denialCaseSummary":{"type":["object","null"],"properties":{"caseNumber":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"payerName":{"type":["string","null"]},"denialReason":{"type":["string","null"]},"primaryCode":{"type":["string","null"]},"denialDate":{"type":["string","null"],"format":"date-time"}},"required":["caseNumber","claimNumber","payerName","denialReason","primaryCode","denialDate"]}},"required":["id","organizationId","denialCaseId","claimId","level","status","outcome","submissionMethod","appealDeadline","payerDecisionDate","totalAppealedAmount","totalRecoveredAmount","submittedAt","confirmationNumber","trackingNumber","createdAt","updatedAt","denialCaseSummary"]}},"required":["appeal"]}},"required":["success","data"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","submissionMethod":"ELECTRONIC_PORTAL","appealDeadline":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","totalAppealedAmount":"example-totalappealedamount","totalRecoveredAmount":"example-totalrecoveredamount","submittedAt":"2026-06-08T10:15:30Z","confirmationNumber":"example-confirmationnumber","trackingNumber":"example-trackingnumber","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","denialCaseSummary":{"caseNumber":"example-casenumber","claimNumber":"example-claimnumber","payerName":"Example appeal_outcome","denialReason":"example-denialreason","primaryCode":"example-primarycode","denialDate":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Concurrent status update conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/appeals/{appealId}/withdraw":{"post":{"operationId":"withdrawAppeal","summary":"Withdraw appeal","description":"Withdraws an active organization-owned appeal with a required reason.\n\n### When to use\nUse this when the provider or organization intentionally ends the appeal workflow before a normal decision.\n\n### Before calling\nConfirm withdrawal is allowed by your operational policy and that any downstream users understand the appeal will be marked withdrawn locally.\n\n### Request guidance\nSend a clear `reason` but avoid unnecessary PHI, credentials, or raw payer messages.\n\n### Request notes\n- Withdrawal is a local workflow update.\n\n### Response semantics\nThe response returns the updated local appeal in a withdrawn workflow state.\n\n### Response notes\n- The returned appeal shows the resulting withdrawn state.\n- This endpoint does not notify a payer by itself.\n\n### Errors and retries\nTreat 404 as missing or wrong tenant context. Re-read after 409 conflicts before retrying.\n\n### Error notes\n- 400 means the reason or workflow state is invalid.\n- 409 means concurrent appeal state changed.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Human-readable withdrawal reason. Keep it concise and safe for audit history."}},"required":["reason"]},"example":{"reason":"example-reason"}}},"description":"Send a clear `reason` but avoid unnecessary PHI, credentials, or raw payer messages."},"responses":{"200":{"description":"Appeal withdrawn","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"submissionMethod":{"type":["string","null"],"enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"totalAppealedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmationNumber":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"denialCaseSummary":{"type":["object","null"],"properties":{"caseNumber":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"payerName":{"type":["string","null"]},"denialReason":{"type":["string","null"]},"primaryCode":{"type":["string","null"]},"denialDate":{"type":["string","null"],"format":"date-time"}},"required":["caseNumber","claimNumber","payerName","denialReason","primaryCode","denialDate"]}},"required":["id","organizationId","denialCaseId","claimId","level","status","outcome","submissionMethod","appealDeadline","payerDecisionDate","totalAppealedAmount","totalRecoveredAmount","submittedAt","confirmationNumber","trackingNumber","createdAt","updatedAt","denialCaseSummary"]}},"required":["appeal"]}},"required":["success","data"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","submissionMethod":"ELECTRONIC_PORTAL","appealDeadline":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","totalAppealedAmount":"example-totalappealedamount","totalRecoveredAmount":"example-totalrecoveredamount","submittedAt":"2026-06-08T10:15:30Z","confirmationNumber":"example-confirmationnumber","trackingNumber":"example-trackingnumber","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","denialCaseSummary":{"caseNumber":"example-casenumber","claimNumber":"example-claimnumber","payerName":"Example withdraw_appeal","denialReason":"example-denialreason","primaryCode":"example-primarycode","denialDate":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Concurrent status update conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/appeals/{appealId}/peer-to-peer":{"post":{"operationId":"schedulePeerToPeer","summary":"Schedule peer-to-peer review","description":"Schedules a peer-to-peer review for an organization-owned appeal.\n\n### When to use\nUse this when the appeal workflow needs a provider-to-payer review call or meeting tracked in QuickRCM.\n\n### Before calling\nConfirm the path `appealId` exists in the authenticated organization, choose the provider, and capture a future scheduled date plus any safe call logistics.\n\n### Request guidance\nSend required `providerUserId`, `providerName`, and future ISO `scheduledDate`. Optional fields are `providerSpecialty`, `scheduledTime`, `duration`, `conferenceLink`, `dialInNumber`, `payerReviewerName`, `payerReviewerTitle`, and `payerPhone`. Do not include payer portal credentials.\n\n### Request notes\n- `scheduledDate` must be a valid future ISO datetime.\n- `duration` is in minutes and is bounded by the schema.\n\n### Response semantics\nThe response creates a local P2P review record. The parent appeal may move to a P2P scheduled status when the status machine allows it.\n\n### Response notes\n- Returns the local P2P review record.\n- This endpoint does not guarantee payer participation.\n\n### Errors and retries\n400 can mean the scheduled date is invalid or not in the future. After a timeout, list P2P reviews for the appeal before retrying.\n\n### Error notes\n- 404 means the appeal is missing or inaccessible.\n- 400 means scheduling or body validation failed.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"providerUserId":{"type":"string","minLength":1,"description":"Required QuickRCM user identifier for the provider assigned to the peer-to-peer review."},"providerName":{"type":"string","minLength":1,"maxLength":255,"description":"Required provider display name for the review."},"providerSpecialty":{"type":"string","minLength":1,"maxLength":255,"description":"Optional provider specialty for review context."},"scheduledDate":{"type":"string","format":"date-time","description":"Required future ISO datetime for the review."},"scheduledTime":{"type":"string","minLength":1,"maxLength":50,"description":"Optional display time when the user needs a human-readable time separate from `scheduledDate`."},"duration":{"type":"integer","minimum":1,"maximum":480,"description":"Optional review duration in minutes; the schema permits 1 through 480."},"conferenceLink":{"type":"string","format":"uri","description":"Optional meeting URL for the review. Treat links as sensitive and avoid embedded credentials."},"dialInNumber":{"type":"string","minLength":1,"maxLength":100,"description":"Optional dial-in number for the review."},"payerReviewerName":{"type":"string","minLength":1,"maxLength":255,"description":"Optional payer reviewer name, when known."},"payerReviewerTitle":{"type":"string","minLength":1,"maxLength":255,"description":"Optional payer reviewer role or title, when known."},"payerPhone":{"type":"string","minLength":1,"maxLength":100,"description":"Optional payer phone number for review logistics."}},"required":["providerUserId","providerName","scheduledDate"]},"example":{"providerUserId":"00000000-0000-4000-8000-000000000001","providerName":"Example schedule_peer_to_peer","scheduledDate":"2026-06-08T10:15:30Z","providerSpecialty":"example-providerspecialty","scheduledTime":"example-scheduledtime","duration":1,"conferenceLink":"example-conferencelink","dialInNumber":"example-dialinnumber","payerReviewerName":"Example schedule_peer_to_peer","payerReviewerTitle":"example-payerreviewertitle","payerPhone":"+15551234567"}}},"description":"Send required `providerUserId`, `providerName`, and future ISO `scheduledDate`. Optional fields are `providerSpecialty`, `scheduledTime`, `duration`, `conferenceLink`, `dialInNumber`, `payerReviewerName`, `payerReviewerTitle`, and `payerPhone`. Do not include payer portal credentials."},"responses":{"200":{"description":"Peer-to-peer review scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"peerToPeerReview":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"appealId":{"type":"string"},"providerUserId":{"type":"string"},"providerName":{"type":"string"},"providerSpecialty":{"type":["string","null"]},"scheduledDate":{"type":["string","null"],"format":"date-time"},"scheduledTime":{"type":["string","null"]},"duration":{"type":["integer","null"]},"conferenceLink":{"type":["string","null"]},"dialInNumber":{"type":["string","null"]},"payerReviewerName":{"type":["string","null"]},"payerReviewerTitle":{"type":["string","null"]},"payerPhone":{"type":["string","null"]},"status":{"type":"string"},"outcome":{"type":["string","null"]},"outcomeNotes":{"type":["string","null"]},"callDuration":{"type":["integer","null"]},"followUpRequired":{"type":"boolean"},"followUpNotes":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","appealId","providerUserId","providerName","providerSpecialty","scheduledDate","scheduledTime","duration","conferenceLink","dialInNumber","payerReviewerName","payerReviewerTitle","payerPhone","status","outcome","outcomeNotes","callDuration","followUpRequired","followUpNotes","createdAt","updatedAt"]}},"required":["peerToPeerReview"]}},"required":["success","data"]},"example":{"success":true,"data":{"peerToPeerReview":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","providerUserId":"00000000-0000-4000-8000-000000000001","providerName":"Example schedule_peer_to_peer","providerSpecialty":"example-providerspecialty","scheduledDate":"2026-06-08T10:15:30Z","scheduledTime":"example-scheduledtime","duration":1,"conferenceLink":"example-conferencelink","dialInNumber":"example-dialinnumber","payerReviewerName":"Example schedule_peer_to_peer","payerReviewerTitle":"example-payerreviewertitle","payerPhone":"+15551234567","status":"active","outcome":"example-outcome","outcomeNotes":"Example schedule_peer_to_peer note","callDuration":1,"followUpRequired":true,"followUpNotes":"Example schedule_peer_to_peer note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/peer-to-peer/{p2pReviewId}/outcome":{"post":{"operationId":"recordPeerToPeerOutcome","summary":"Record peer-to-peer outcome","description":"Records status and outcome details for an existing peer-to-peer review.\n\n### When to use\nUse this after the P2P call is completed, missed, cancelled, or otherwise resolved.\n\n### Before calling\nConfirm the path `p2pReviewId` belongs to the authenticated organization and capture call outcome details only when known.\n\n### Request guidance\nSend required `status` and optional `outcome`, `outcomeNotes`, `callDuration`, `followUpRequired`, and `followUpNotes`. Keep notes concise and avoid raw clinical transcripts.\n\n### Request notes\n- `callDuration` is a whole-minute value.\n- `followUpRequired` should be paired with `followUpNotes` when action is needed.\n\n### Response semantics\nThe response updates the local P2P review record and does not post appeal payment or payer adjudication by itself.\n\n### Response notes\n- Returns the updated P2P review.\n- Appeal outcome still uses recordAppealOutcome when applicable.\n\n### Errors and retries\nAfter a timeout, read the P2P review before retrying to avoid overwriting follow-up notes.\n\n### Error notes\n- 404 means the P2P review is missing or wrong-organization.\n- 400 means status or body validation failed.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"p2pReviewId","in":"path","description":"Tenant-scoped QuickRCM peer-to-peer review identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["REQUESTED","SCHEDULED","CONFIRMED","COMPLETED","CANCELLED","NO_SHOW_PAYER","NO_SHOW_PROVIDER","RESCHEDULED"],"description":"Required target peer-to-peer review status using the P2P status enum."},"outcome":{"type":"string","minLength":1,"maxLength":100,"description":"Optional short outcome label or category for the review."},"outcomeNotes":{"type":"string","minLength":1,"maxLength":4000,"description":"Optional outcome narrative for the review. Avoid raw transcripts and unnecessary PHI."},"callDuration":{"type":["integer","null"],"minimum":0,"maximum":1440,"description":"Optional call duration in whole minutes; the schema permits 0 through 1440."},"followUpRequired":{"type":"boolean","description":"Optional boolean indicating whether additional action is needed after the review."},"followUpNotes":{"type":"string","minLength":1,"maxLength":4000,"description":"Optional follow-up instructions or context."}},"required":["status"]},"example":{"status":"REQUESTED","outcome":"example-outcome","outcomeNotes":"Example peer_to_peer_outcome note","callDuration":1,"followUpRequired":true,"followUpNotes":"Example peer_to_peer_outcome note"}}},"description":"Send required `status` and optional `outcome`, `outcomeNotes`, `callDuration`, `followUpRequired`, and `followUpNotes`. Keep notes concise and avoid raw clinical transcripts."},"responses":{"200":{"description":"Peer-to-peer outcome recorded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"peerToPeerReview":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"appealId":{"type":"string"},"providerUserId":{"type":"string"},"providerName":{"type":"string"},"providerSpecialty":{"type":["string","null"]},"scheduledDate":{"type":["string","null"],"format":"date-time"},"scheduledTime":{"type":["string","null"]},"duration":{"type":["integer","null"]},"conferenceLink":{"type":["string","null"]},"dialInNumber":{"type":["string","null"]},"payerReviewerName":{"type":["string","null"]},"payerReviewerTitle":{"type":["string","null"]},"payerPhone":{"type":["string","null"]},"status":{"type":"string"},"outcome":{"type":["string","null"]},"outcomeNotes":{"type":["string","null"]},"callDuration":{"type":["integer","null"]},"followUpRequired":{"type":"boolean"},"followUpNotes":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","appealId","providerUserId","providerName","providerSpecialty","scheduledDate","scheduledTime","duration","conferenceLink","dialInNumber","payerReviewerName","payerReviewerTitle","payerPhone","status","outcome","outcomeNotes","callDuration","followUpRequired","followUpNotes","createdAt","updatedAt"]}},"required":["peerToPeerReview"]}},"required":["success","data"]},"example":{"success":true,"data":{"peerToPeerReview":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","providerUserId":"00000000-0000-4000-8000-000000000001","providerName":"Example peer_to_peer_outcome","providerSpecialty":"example-providerspecialty","scheduledDate":"2026-06-08T10:15:30Z","scheduledTime":"example-scheduledtime","duration":1,"conferenceLink":"example-conferencelink","dialInNumber":"example-dialinnumber","payerReviewerName":"Example peer_to_peer_outcome","payerReviewerTitle":"example-payerreviewertitle","payerPhone":"+15551234567","status":"active","outcome":"example-outcome","outcomeNotes":"Example peer_to_peer_outcome note","callDuration":1,"followUpRequired":true,"followUpNotes":"Example peer_to_peer_outcome note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Peer-to-peer review not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/peer-to-peer/{p2pReviewId}":{"get":{"operationId":"getAppealPeerToPeerReview","summary":"Get peer-to-peer review","description":"Returns one organization-scoped peer-to-peer review.\n\n### When to use\nUse this after list or scheduling responses provide a `p2pReviewId`.\n\n### Before calling\nConfirm the identifier came from the same organization context as the API key.\n\n### Request guidance\nPass only the path `p2pReviewId`; no tenant selector is needed.\n\n### Request notes\n- Use ids returned from list or schedule responses.\n- Never guess P2P review IDs across tenants.\n\n### Response semantics\nThe response contains local P2P schedule, reviewer, status, outcome, and follow-up metadata.\n\n### Response notes\n- Returns local review metadata.\n- Does not include call recordings or raw transcripts.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization review context. Retry transient 5xx with backoff.\n\n### Error notes\n- 404 can mean missing or inaccessible.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"p2pReviewId","in":"path","description":"Tenant-scoped QuickRCM peer-to-peer review identifier selected from the path."}],"responses":{"200":{"description":"Peer-to-peer review","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"peerToPeerReview":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"appealId":{"type":"string"},"providerUserId":{"type":"string"},"providerName":{"type":"string"},"providerSpecialty":{"type":["string","null"]},"scheduledDate":{"type":["string","null"],"format":"date-time"},"scheduledTime":{"type":["string","null"]},"duration":{"type":["integer","null"]},"conferenceLink":{"type":["string","null"]},"dialInNumber":{"type":["string","null"]},"payerReviewerName":{"type":["string","null"]},"payerReviewerTitle":{"type":["string","null"]},"payerPhone":{"type":["string","null"]},"status":{"type":"string"},"outcome":{"type":["string","null"]},"outcomeNotes":{"type":["string","null"]},"callDuration":{"type":["integer","null"]},"followUpRequired":{"type":"boolean"},"followUpNotes":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","appealId","providerUserId","providerName","providerSpecialty","scheduledDate","scheduledTime","duration","conferenceLink","dialInNumber","payerReviewerName","payerReviewerTitle","payerPhone","status","outcome","outcomeNotes","callDuration","followUpRequired","followUpNotes","createdAt","updatedAt"]}},"required":["peerToPeerReview"]}},"required":["success","data"]},"example":{"success":true,"data":{"peerToPeerReview":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","providerUserId":"00000000-0000-4000-8000-000000000001","providerName":"Example appeal_peer_to_peer_review","providerSpecialty":"example-providerspecialty","scheduledDate":"2026-06-08T10:15:30Z","scheduledTime":"example-scheduledtime","duration":1,"conferenceLink":"example-conferencelink","dialInNumber":"example-dialinnumber","payerReviewerName":"Example appeal_peer_to_peer_review","payerReviewerTitle":"example-payerreviewertitle","payerPhone":"+15551234567","status":"active","outcome":"example-outcome","outcomeNotes":"Example appeal_peer_to_peer_review note","callDuration":1,"followUpRequired":true,"followUpNotes":"Example appeal_peer_to_peer_review note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Peer-to-peer review not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/peer-to-peer/{p2pReviewId}/reschedule":{"put":{"operationId":"rescheduleAppealPeerToPeerReview","summary":"Reschedule peer-to-peer review","description":"Reschedules a peer-to-peer review with a required reason.\n\n### When to use\nUse this when the provider, payer, or organization changes the review date or logistics before the review completes.\n\n### Before calling\nRead the current review selected by path `p2pReviewId` and choose a new future scheduled date plus safe logistics.\n\n### Request guidance\nSend required future ISO `scheduledDate` and required `reason`. Optional scheduling/logistics fields are `scheduledTime`, `duration`, `conferenceLink`, and `dialInNumber`.\n\n### Request notes\n- Use a future ISO datetime for `scheduledDate`.\n\n### Response semantics\nThe response returns the updated P2P review, with local status set to rescheduled and follow-up context retained.\n\n### Response notes\n- Returns the updated local P2P review.\n- An appeal activity is recorded internally.\n\n### Errors and retries\nTreat past dates as non-retryable 400s. Re-read review state after 409 conflicts.\n\n### Error notes\n- 404 means the review is missing or inaccessible.\n- 409 indicates concurrent P2P update conflict.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"p2pReviewId","in":"path","description":"Tenant-scoped QuickRCM peer-to-peer review identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scheduledDate":{"type":"string","format":"date-time","description":"Required future ISO datetime for the rescheduled review."},"scheduledTime":{"type":"string","minLength":1,"maxLength":50,"description":"Optional display time when needed separately from `scheduledDate`."},"duration":{"type":"integer","minimum":1,"maximum":480,"description":"Optional review duration in minutes; the schema permits 1 through 480."},"conferenceLink":{"type":"string","format":"uri","description":"Optional replacement meeting URL. Treat links as sensitive and avoid embedded credentials."},"dialInNumber":{"type":"string","minLength":1,"maxLength":100,"description":"Optional replacement dial-in number."},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Required reason for rescheduling. Avoid raw payer messages or sensitive content."}},"required":["scheduledDate","reason"]},"example":{"scheduledDate":"2026-06-08T10:15:30Z","reason":"example-reason","scheduledTime":"example-scheduledtime","duration":1,"conferenceLink":"example-conferencelink","dialInNumber":"example-dialinnumber"}}},"description":"Send required future ISO `scheduledDate` and required `reason`. Optional scheduling/logistics fields are `scheduledTime`, `duration`, `conferenceLink`, and `dialInNumber`."},"responses":{"200":{"description":"Peer-to-peer review rescheduled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"peerToPeerReview":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"appealId":{"type":"string"},"providerUserId":{"type":"string"},"providerName":{"type":"string"},"providerSpecialty":{"type":["string","null"]},"scheduledDate":{"type":["string","null"],"format":"date-time"},"scheduledTime":{"type":["string","null"]},"duration":{"type":["integer","null"]},"conferenceLink":{"type":["string","null"]},"dialInNumber":{"type":["string","null"]},"payerReviewerName":{"type":["string","null"]},"payerReviewerTitle":{"type":["string","null"]},"payerPhone":{"type":["string","null"]},"status":{"type":"string"},"outcome":{"type":["string","null"]},"outcomeNotes":{"type":["string","null"]},"callDuration":{"type":["integer","null"]},"followUpRequired":{"type":"boolean"},"followUpNotes":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","appealId","providerUserId","providerName","providerSpecialty","scheduledDate","scheduledTime","duration","conferenceLink","dialInNumber","payerReviewerName","payerReviewerTitle","payerPhone","status","outcome","outcomeNotes","callDuration","followUpRequired","followUpNotes","createdAt","updatedAt"]}},"required":["peerToPeerReview"]}},"required":["success","data"]},"example":{"success":true,"data":{"peerToPeerReview":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","providerUserId":"00000000-0000-4000-8000-000000000001","providerName":"Example reschedule_appeal_peer_to_peer_review","providerSpecialty":"example-providerspecialty","scheduledDate":"2026-06-08T10:15:30Z","scheduledTime":"example-scheduledtime","duration":1,"conferenceLink":"example-conferencelink","dialInNumber":"example-dialinnumber","payerReviewerName":"Example reschedule_appeal_peer_to_peer_review","payerReviewerTitle":"example-payerreviewertitle","payerPhone":"+15551234567","status":"active","outcome":"example-outcome","outcomeNotes":"Example reschedule_appeal_peer_to_peer_review note","callDuration":1,"followUpRequired":true,"followUpNotes":"Example reschedule_appeal_peer_to_peer_review note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Peer-to-peer review not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Concurrent peer-to-peer update conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/appeals/peer-to-peer/{p2pReviewId}/cancel":{"put":{"operationId":"cancelAppealPeerToPeerReview","summary":"Cancel peer-to-peer review","description":"Cancels a peer-to-peer review with a required reason.\n\n### When to use\nUse this when a scheduled P2P review should no longer remain active in QuickRCM.\n\n### Before calling\nConfirm cancellation is intended and capture the payer or provider reason if it is operationally safe to store.\n\n### Request guidance\nSend only the path `p2pReviewId` and a concise `reason` in the body.\n\n### Request notes\n- Cancellation is local workflow state; it does not automatically notify the payer.\n\n### Response semantics\nThe response returns the local P2P review with cancelled status and reason context.\n\n### Response notes\n- Returns the cancelled local review.\n- Follow-up fields are cleared by the implementation.\n\n### Errors and retries\nRe-read review state after timeouts or 409 conflicts before retrying.\n\n### Error notes\n- 404 means the P2P review is missing or inaccessible.\n- 400 means request validation failed.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"p2pReviewId","in":"path","description":"Tenant-scoped QuickRCM peer-to-peer review identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Reason for cancelling the peer-to-peer review."}},"required":["reason"]},"example":{"reason":"example-reason"}}},"description":"Send only the path `p2pReviewId` and a concise `reason` in the body."},"responses":{"200":{"description":"Peer-to-peer review cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"peerToPeerReview":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"appealId":{"type":"string"},"providerUserId":{"type":"string"},"providerName":{"type":"string"},"providerSpecialty":{"type":["string","null"]},"scheduledDate":{"type":["string","null"],"format":"date-time"},"scheduledTime":{"type":["string","null"]},"duration":{"type":["integer","null"]},"conferenceLink":{"type":["string","null"]},"dialInNumber":{"type":["string","null"]},"payerReviewerName":{"type":["string","null"]},"payerReviewerTitle":{"type":["string","null"]},"payerPhone":{"type":["string","null"]},"status":{"type":"string"},"outcome":{"type":["string","null"]},"outcomeNotes":{"type":["string","null"]},"callDuration":{"type":["integer","null"]},"followUpRequired":{"type":"boolean"},"followUpNotes":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","appealId","providerUserId","providerName","providerSpecialty","scheduledDate","scheduledTime","duration","conferenceLink","dialInNumber","payerReviewerName","payerReviewerTitle","payerPhone","status","outcome","outcomeNotes","callDuration","followUpRequired","followUpNotes","createdAt","updatedAt"]}},"required":["peerToPeerReview"]}},"required":["success","data"]},"example":{"success":true,"data":{"peerToPeerReview":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","providerUserId":"00000000-0000-4000-8000-000000000001","providerName":"Example cancel_appeal_peer_to_peer_review","providerSpecialty":"example-providerspecialty","scheduledDate":"2026-06-08T10:15:30Z","scheduledTime":"example-scheduledtime","duration":1,"conferenceLink":"example-conferencelink","dialInNumber":"example-dialinnumber","payerReviewerName":"Example cancel_appeal_peer_to_peer_review","payerReviewerTitle":"example-payerreviewertitle","payerPhone":"+15551234567","status":"active","outcome":"example-outcome","outcomeNotes":"Example cancel_appeal_peer_to_peer_review note","callDuration":1,"followUpRequired":true,"followUpNotes":"Example cancel_appeal_peer_to_peer_review note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Peer-to-peer review not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Concurrent peer-to-peer update conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/appeals/{appealId}/documents":{"get":{"operationId":"listAppealDocuments","summary":"List appeal documents","description":"Lists supporting document rows for an organization-owned appeal.\n\n### When to use\nUse this to show appeal packet readiness, find missing documents, or choose a document before upload, review, or download actions.\n\n### Before calling\nResolve the appeal id from a trusted QuickRCM response.\n\n### Request guidance\nPass only the tenant-scoped `appealId` path parameter. File storage keys are not part of the public request or response.\n\n### Request notes\n- Use this before compiling a packet or checking upload status.\n- Use document IDs from this endpoint for document-specific actions.\n\n### Response semantics\nThe response returns document metadata and sanitized file metadata when linked; it does not expose S3 keys.\n\n### Response notes\n- File metadata excludes storage keys.\n- Document status drives review and packet readiness.\n\n### Errors and retries\nTreat 404 as missing appeal or wrong tenant. Back off on 429 for polling.\n\n### Error notes\n- 404 means the appeal is unavailable to this tenant.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"responses":{"200":{"description":"Appeal documents","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"appealId":{"type":"string"},"documentType":{"type":"string","enum":["APPEAL_LETTER","CLINICAL_NOTES","OPERATIVE_REPORT","PATHOLOGY_REPORT","RADIOLOGY_REPORT","LAB_RESULTS","PRIOR_AUTHORIZATION","REFERRAL","MEDICAL_RECORDS","LETTER_OF_MEDICAL_NECESSITY","PEER_REVIEWED_LITERATURE","CLINICAL_GUIDELINES","PAYER_POLICY_EXCERPT","CONTRACT_EXCERPT","PHYSICIAN_ATTESTATION","PATIENT_CONSENT","CORRECTED_CLAIM_FORM","ITEMIZED_BILL","EOB_REMITTANCE","PAYER_DENIAL_LETTER","PAYER_RESPONSE","OTHER"]},"documentName":{"type":"string"},"status":{"type":"string","enum":["REQUIRED","REQUESTED","IN_PROGRESS","UPLOADED","REVIEWED","APPROVED","REJECTED_REDO"]},"fileId":{"type":["string","null"]},"dueDate":{"type":["string","null"],"format":"date-time"},"uploadedAt":{"type":["string","null"],"format":"date-time"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewNotes":{"type":["string","null"]},"isRequired":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"file":{"type":["object","null"],"properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","filename","mimeType","sizeBytes","createdAt","updatedAt"]}},"required":["id","appealId","documentType","documentName","status","fileId","dueDate","uploadedAt","reviewedAt","reviewNotes","isRequired","createdAt","updatedAt","file"]}}},"required":["documents"]}},"required":["success","data"]},"example":{"success":true,"data":{"documents":[{"id":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","documentType":"APPEAL_LETTER","documentName":"Example appeal_document","status":"REQUIRED","fileId":"00000000-0000-4000-8000-000000000001","dueDate":"2026-06-08T10:15:30Z","uploadedAt":"2026-06-08T10:15:30Z","reviewedAt":"2026-06-08T10:15:30Z","reviewNotes":"Example appeal_document note","isRequired":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","file":{"id":"00000000-0000-4000-8000-000000000001","filename":"Example appeal_document","mimeType":"example-mimetype","sizeBytes":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}},"post":{"operationId":"addAppealSupportingDocument","summary":"Add appeal supporting document","description":"Adds a required supporting document placeholder to an appeal.\n\n### When to use\nUse this when an appeal needs a specific document tracked before upload or review.\n\n### Before calling\nConfirm the appeal exists and choose a document type from the Appeals schema.\n\n### Request guidance\nSend a `documentType` enum value and human-readable `documentName`. Do not embed file content in this request.\n\n### Request notes\n- Upload file bytes separately through the upload URL workflow.\n- `documentName` should describe the artifact without unnecessary PHI.\n\n### Response semantics\nThe response returns the created local document row, initially tracked as required by the document workflow.\n\n### Response notes\n- Returns the new document metadata.\n- No file is uploaded by this endpoint.\n\n### Errors and retries\nAfter network timeouts, list appeal documents before retrying to avoid duplicate placeholders.\n\n### Error notes\n- 404 means the appeal is missing or inaccessible.\n- 400 means the document type or name failed validation.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"documentType":{"type":"string","enum":["APPEAL_LETTER","CLINICAL_NOTES","OPERATIVE_REPORT","PATHOLOGY_REPORT","RADIOLOGY_REPORT","LAB_RESULTS","PRIOR_AUTHORIZATION","REFERRAL","MEDICAL_RECORDS","LETTER_OF_MEDICAL_NECESSITY","PEER_REVIEWED_LITERATURE","CLINICAL_GUIDELINES","PAYER_POLICY_EXCERPT","CONTRACT_EXCERPT","PHYSICIAN_ATTESTATION","PATIENT_CONSENT","CORRECTED_CLAIM_FORM","ITEMIZED_BILL","EOB_REMITTANCE","PAYER_DENIAL_LETTER","PAYER_RESPONSE","OTHER"],"description":"Appeal supporting document category such as CLINICAL_NOTES, PAYER_DENIAL_LETTER, LETTER_OF_MEDICAL_NECESSITY, or OTHER."},"documentName":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the appeal supporting document."}},"required":["documentType","documentName"]},"example":{"documentType":"APPEAL_LETTER","documentName":"Example add_appeal_supporting_document"}}},"description":"Send a `documentType` enum value and human-readable `documentName`. Do not embed file content in this request."},"responses":{"201":{"description":"Appeal supporting document added","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"appealId":{"type":"string"},"documentType":{"type":"string","enum":["APPEAL_LETTER","CLINICAL_NOTES","OPERATIVE_REPORT","PATHOLOGY_REPORT","RADIOLOGY_REPORT","LAB_RESULTS","PRIOR_AUTHORIZATION","REFERRAL","MEDICAL_RECORDS","LETTER_OF_MEDICAL_NECESSITY","PEER_REVIEWED_LITERATURE","CLINICAL_GUIDELINES","PAYER_POLICY_EXCERPT","CONTRACT_EXCERPT","PHYSICIAN_ATTESTATION","PATIENT_CONSENT","CORRECTED_CLAIM_FORM","ITEMIZED_BILL","EOB_REMITTANCE","PAYER_DENIAL_LETTER","PAYER_RESPONSE","OTHER"]},"documentName":{"type":"string"},"status":{"type":"string","enum":["REQUIRED","REQUESTED","IN_PROGRESS","UPLOADED","REVIEWED","APPROVED","REJECTED_REDO"]},"fileId":{"type":["string","null"]},"dueDate":{"type":["string","null"],"format":"date-time"},"uploadedAt":{"type":["string","null"],"format":"date-time"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewNotes":{"type":["string","null"]},"isRequired":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"file":{"type":["object","null"],"properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","filename","mimeType","sizeBytes","createdAt","updatedAt"]}},"required":["id","appealId","documentType","documentName","status","fileId","dueDate","uploadedAt","reviewedAt","reviewNotes","isRequired","createdAt","updatedAt","file"]}},"required":["document"]}},"required":["success","data"]},"example":{"success":true,"data":{"document":{"id":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","documentType":"APPEAL_LETTER","documentName":"Example add_appeal_supporting_document","status":"REQUIRED","fileId":"00000000-0000-4000-8000-000000000001","dueDate":"2026-06-08T10:15:30Z","uploadedAt":"2026-06-08T10:15:30Z","reviewedAt":"2026-06-08T10:15:30Z","reviewNotes":"Example add_appeal_supporting_document note","isRequired":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","file":{"id":"00000000-0000-4000-8000-000000000001","filename":"Example add_appeal_supporting_document","mimeType":"example-mimetype","sizeBytes":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/{appealId}/documents/checklist":{"post":{"operationId":"generateAppealDocumentChecklist","summary":"Generate appeal document checklist","description":"Generates required supporting document checklist rows for an appeal.\n\n### When to use\nUse this when starting appeal packet preparation and you want QuickRCM to create missing checklist items.\n\n### Before calling\nConfirm the appeal belongs to the organization and that duplicate checklist generation is acceptable for any missing items.\n\n### Request guidance\nThe request body is intentionally empty. Pass the appeal id in the path.\n\n### Request notes\n- No document files are uploaded by this endpoint.\n- Generated document names come from the template or fallback document type logic.\n\n### Response semantics\nThe response returns document rows created by the checklist generation. Existing matching document types are skipped rather than duplicated by the implementation.\n\n### Response notes\n- Returns created document rows.\n- The array may be empty when all required items already exist.\n\n### Errors and retries\nIf the request times out, list appeal documents before retrying to see which checklist rows were created.\n\n### Error notes\n- 404 means the appeal is missing or inaccessible.\n- 400 means request validation failed.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"The request body is intentionally empty. Pass the appeal id in the path."},"responses":{"201":{"description":"Appeal document checklist generated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"appealId":{"type":"string"},"documentType":{"type":"string","enum":["APPEAL_LETTER","CLINICAL_NOTES","OPERATIVE_REPORT","PATHOLOGY_REPORT","RADIOLOGY_REPORT","LAB_RESULTS","PRIOR_AUTHORIZATION","REFERRAL","MEDICAL_RECORDS","LETTER_OF_MEDICAL_NECESSITY","PEER_REVIEWED_LITERATURE","CLINICAL_GUIDELINES","PAYER_POLICY_EXCERPT","CONTRACT_EXCERPT","PHYSICIAN_ATTESTATION","PATIENT_CONSENT","CORRECTED_CLAIM_FORM","ITEMIZED_BILL","EOB_REMITTANCE","PAYER_DENIAL_LETTER","PAYER_RESPONSE","OTHER"]},"documentName":{"type":"string"},"status":{"type":"string","enum":["REQUIRED","REQUESTED","IN_PROGRESS","UPLOADED","REVIEWED","APPROVED","REJECTED_REDO"]},"fileId":{"type":["string","null"]},"dueDate":{"type":["string","null"],"format":"date-time"},"uploadedAt":{"type":["string","null"],"format":"date-time"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewNotes":{"type":["string","null"]},"isRequired":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"file":{"type":["object","null"],"properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","filename","mimeType","sizeBytes","createdAt","updatedAt"]}},"required":["id","appealId","documentType","documentName","status","fileId","dueDate","uploadedAt","reviewedAt","reviewNotes","isRequired","createdAt","updatedAt","file"]}}},"required":["documents"]}},"required":["success","data"]},"example":{"success":true,"data":{"documents":[{"id":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","documentType":"APPEAL_LETTER","documentName":"Example appeal_document_checklist","status":"REQUIRED","fileId":"00000000-0000-4000-8000-000000000001","dueDate":"2026-06-08T10:15:30Z","uploadedAt":"2026-06-08T10:15:30Z","reviewedAt":"2026-06-08T10:15:30Z","reviewNotes":"Example appeal_document_checklist note","isRequired":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","file":{"id":"00000000-0000-4000-8000-000000000001","filename":"Example appeal_document_checklist","mimeType":"example-mimetype","sizeBytes":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/documents/{documentId}/download-url":{"post":{"operationId":"createAppealDocumentDownload","summary":"Create appeal document download URL","description":"Creates a short-lived presigned download URL for a linked appeal document file.\n\n### When to use\nUse this when an authorized integration needs to retrieve a document file already linked to an appeal supporting document.\n\n### Before calling\nGet the `documentId` from listAppealDocuments and verify the document has a linked file.\n\n### Request guidance\nSend an empty JSON body and the document id in the path. Do not ask for or store S3 object keys.\n\n### Request notes\n- Use the URL promptly; it is time-limited.\n- Do not log the presigned URL in application logs.\n\n### Response semantics\nThe response includes a download URL, `expiresInSeconds`, document id, and sanitized file metadata. Current implementation uses a 900-second download URL expiry.\n\n### Response notes\n- `downloadUrl` is a credential-bearing URL and should be handled as sensitive.\n\n### Errors and retries\n400 means the document exists but has no downloadable file. 404 means the document is missing or not owned by the organization.\n\n### Error notes\n- 400 means no linked downloadable file exists.\n- 404 means missing or inaccessible document.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path","description":"Tenant-scoped QuickRCM appeal supporting document identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"Send an empty JSON body and the document id in the path. Do not ask for or store S3 object keys."},"responses":{"200":{"description":"Appeal document download URL","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"documentId":{"type":"string"},"downloadUrl":{"type":"string","format":"uri"},"expiresInSeconds":{"type":"integer"},"file":{"type":["object","null"],"properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","filename","mimeType","sizeBytes","createdAt","updatedAt"]}},"required":["documentId","downloadUrl","expiresInSeconds","file"]}},"required":["success","data"]},"example":{"success":true,"data":{"documentId":"00000000-0000-4000-8000-000000000001","downloadUrl":"https://example.quickintell.com/resource","expiresInSeconds":1,"file":{"id":"00000000-0000-4000-8000-000000000001","filename":"Example appeal_document_download","mimeType":"example-mimetype","sizeBytes":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/documents/{documentId}":{"delete":{"operationId":"deleteAppealDocument","summary":"Delete appeal document","description":"Deletes an organization-scoped appeal supporting document row.\n\n### When to use\nUse this when a document placeholder or metadata row should be removed from an appeal workflow.\n\n### Before calling\nConfirm the document id belongs to the intended appeal and removal will not break packet readiness.\n\n### Request guidance\nPass the `documentId` path parameter and an empty JSON body.\n\n### Request notes\n- Use document ids from listAppealDocuments.\n- Do not use this endpoint to delete unrelated file records.\n\n### Response semantics\nThe response confirms the document row deletion. The public API response does not claim that underlying file storage was deleted.\n\n### Response notes\n- Returns `deleted: true` with the document id.\n- Underlying object-storage deletion is not exposed in the response.\n\n### Errors and retries\nAfter a timeout, list appeal documents before retrying to avoid treating an already-deleted row as a failure.\n\n### Error notes\n- 404 means the document is missing or inaccessible.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path","description":"Tenant-scoped QuickRCM appeal supporting document identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"Pass the `documentId` path parameter and an empty JSON body."},"responses":{"200":{"description":"Appeal document deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"documentId":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["documentId","deleted"]}},"required":["success","data"]},"example":{"success":true,"data":{"documentId":"00000000-0000-4000-8000-000000000001","deleted":true}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/documents/{documentId}/upload-url":{"post":{"operationId":"createAppealDocumentUpload","summary":"Create appeal document upload URL","description":"Creates a presigned upload URL and local file record for an appeal supporting document.\n\n### When to use\nUse this before uploading document bytes to storage and linking the resulting file record to the document.\n\n### Before calling\nCreate or list the target supporting document and know the file name, MIME type, and byte size.\n\n### Request guidance\nPass `documentId` in the path and send required `fileName`, `fileType`, and `fileSize` in the body. The schema limits `fileSize` to 100,000,000 bytes. Do not send storage keys or file bytes to this JSON endpoint.\n\n### Request notes\n- Upload file bytes to the returned URL outside this API call.\n- Link the resulting file record with linkAppealDocumentFile.\n\n### Response semantics\nThe response contains `uploadUrl`, `documentId`, and sanitized file metadata. Storage keys are intentionally omitted.\n\n### Response notes\n- `uploadUrl` is sensitive and time-limited.\n- `file` metadata omits S3 keys.\n\n### Errors and retries\nIf upload URL creation succeeds but file upload fails, either retry upload to the same URL while valid or create a new upload URL according to client policy.\n\n### Error notes\n- 404 means the document is missing or inaccessible.\n- 400 means file metadata failed validation.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path","description":"Tenant-scoped QuickRCM appeal supporting document identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Required original or display file name for the upload target; max length is 255 characters."},"fileType":{"type":"string","minLength":1,"maxLength":255,"description":"Required MIME type or content type for the file being uploaded; max length is 255 characters."},"fileSize":{"type":"integer","minimum":1,"maximum":100000000,"description":"Required file size in bytes; the schema permits 1 through 100,000,000."}},"required":["fileName","fileType","fileSize"]},"example":{"fileName":"Example appeal_document_upload","fileType":"example-filetype","fileSize":1}}},"description":"Pass `documentId` in the path and send required `fileName`, `fileType`, and `fileSize` in the body. The schema limits `fileSize` to 100,000,000 bytes. Do not send storage keys or file bytes to this JSON endpoint."},"responses":{"200":{"description":"Appeal document upload URL","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"uploadUrl":{"type":"string","format":"uri"},"documentId":{"type":"string"},"file":{"type":["object","null"],"properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","filename","mimeType","sizeBytes","createdAt","updatedAt"]}},"required":["uploadUrl","documentId","file"]}},"required":["success","data"]},"example":{"success":true,"data":{"uploadUrl":"https://example.quickintell.com/resource","documentId":"00000000-0000-4000-8000-000000000001","file":{"id":"00000000-0000-4000-8000-000000000001","filename":"Example appeal_document_upload","mimeType":"example-mimetype","sizeBytes":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/documents/{documentId}/link-file":{"post":{"operationId":"linkAppealDocumentFile","summary":"Link appeal document file","description":"Links an organization-owned file record to an appeal supporting document.\n\n### When to use\nUse this after creating an upload URL and uploading the file bytes, so the document workflow can move to uploaded status.\n\n### Before calling\nConfirm both the document id and file id were created under the same organization.\n\n### Request guidance\nSend `fileId` in the body and `documentId` in the path. Do not send storage keys.\n\n### Request notes\n- `fileId` must belong to the same organization.\n- Use createAppealDocumentUpload before this endpoint when uploading a new file.\n\n### Response semantics\nThe response returns the updated document metadata. The implementation marks the document as uploaded when the link succeeds.\n\n### Response notes\n- The updated document includes sanitized file metadata.\n- Storage keys remain hidden.\n\n### Errors and retries\nIf a timeout occurs, list documents and inspect fileId/status before retrying.\n\n### Error notes\n- 404 means document or file is missing or inaccessible.\n- 400 can mean the file record is incomplete.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path","description":"Tenant-scoped QuickRCM appeal supporting document identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string","minLength":1,"description":"QuickRCM file record identifier to link to the document."}},"required":["fileId"]},"example":{"fileId":"00000000-0000-4000-8000-000000000001"}}},"description":"Send `fileId` in the body and `documentId` in the path. Do not send storage keys."},"responses":{"200":{"description":"Appeal document file linked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"appealId":{"type":"string"},"documentType":{"type":"string","enum":["APPEAL_LETTER","CLINICAL_NOTES","OPERATIVE_REPORT","PATHOLOGY_REPORT","RADIOLOGY_REPORT","LAB_RESULTS","PRIOR_AUTHORIZATION","REFERRAL","MEDICAL_RECORDS","LETTER_OF_MEDICAL_NECESSITY","PEER_REVIEWED_LITERATURE","CLINICAL_GUIDELINES","PAYER_POLICY_EXCERPT","CONTRACT_EXCERPT","PHYSICIAN_ATTESTATION","PATIENT_CONSENT","CORRECTED_CLAIM_FORM","ITEMIZED_BILL","EOB_REMITTANCE","PAYER_DENIAL_LETTER","PAYER_RESPONSE","OTHER"]},"documentName":{"type":"string"},"status":{"type":"string","enum":["REQUIRED","REQUESTED","IN_PROGRESS","UPLOADED","REVIEWED","APPROVED","REJECTED_REDO"]},"fileId":{"type":["string","null"]},"dueDate":{"type":["string","null"],"format":"date-time"},"uploadedAt":{"type":["string","null"],"format":"date-time"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewNotes":{"type":["string","null"]},"isRequired":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"file":{"type":["object","null"],"properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","filename","mimeType","sizeBytes","createdAt","updatedAt"]}},"required":["id","appealId","documentType","documentName","status","fileId","dueDate","uploadedAt","reviewedAt","reviewNotes","isRequired","createdAt","updatedAt","file"]}},"required":["document"]}},"required":["success","data"]},"example":{"success":true,"data":{"document":{"id":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","documentType":"APPEAL_LETTER","documentName":"Example link_appeal_document_file","status":"REQUIRED","fileId":"00000000-0000-4000-8000-000000000001","dueDate":"2026-06-08T10:15:30Z","uploadedAt":"2026-06-08T10:15:30Z","reviewedAt":"2026-06-08T10:15:30Z","reviewNotes":"Example link_appeal_document_file note","isRequired":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","file":{"id":"00000000-0000-4000-8000-000000000001","filename":"Example link_appeal_document_file","mimeType":"example-mimetype","sizeBytes":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Document or file not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/documents/{documentId}/status":{"put":{"operationId":"updateAppealDocumentStatus","summary":"Update appeal document status","description":"Reviews, approves, or rejects an appeal supporting document.\n\n### When to use\nUse this after a document is uploaded and a reviewer needs to advance it through review state.\n\n### Before calling\nRead the current document status and choose an allowed review status transition.\n\n### Request guidance\nPass `documentId` in the path and send required `status` plus optional `note`. Allowed request statuses are `REVIEWED`, `APPROVED`, and `REJECTED_REDO`.\n\n### Request notes\n- Use `REJECTED_REDO` when the file must be corrected and uploaded again.\n- Keep review notes concise and avoid unnecessary PHI.\n\n### Response semantics\nThe response returns the updated local document. Request `note` is stored as review context; returned document metadata may include `reviewedAt` and `reviewNotes` when applicable.\n\n### Response notes\n- Returned document metadata includes reviewedAt/reviewNotes when applicable.\n- Only document workflow state changes here.\n\n### Errors and retries\nTreat invalid transitions as 400s. Re-read document state after 409 conflicts.\n\n### Error notes\n- 400 can mean an invalid transition.\n- 409 means concurrent document status update conflict.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path","description":"Tenant-scoped QuickRCM appeal supporting document identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["REVIEWED","APPROVED","REJECTED_REDO"],"description":"Required document review status: REVIEWED, APPROVED, or REJECTED_REDO."},"note":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional review note for the document status update. Keep concise and avoid unnecessary PHI."}},"required":["status"]},"example":{"status":"REVIEWED","note":"Example appeal_document_statu note"}}},"description":"Pass `documentId` in the path and send required `status` plus optional `note`. Allowed request statuses are `REVIEWED`, `APPROVED`, and `REJECTED_REDO`."},"responses":{"200":{"description":"Appeal document status updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"appealId":{"type":"string"},"documentType":{"type":"string","enum":["APPEAL_LETTER","CLINICAL_NOTES","OPERATIVE_REPORT","PATHOLOGY_REPORT","RADIOLOGY_REPORT","LAB_RESULTS","PRIOR_AUTHORIZATION","REFERRAL","MEDICAL_RECORDS","LETTER_OF_MEDICAL_NECESSITY","PEER_REVIEWED_LITERATURE","CLINICAL_GUIDELINES","PAYER_POLICY_EXCERPT","CONTRACT_EXCERPT","PHYSICIAN_ATTESTATION","PATIENT_CONSENT","CORRECTED_CLAIM_FORM","ITEMIZED_BILL","EOB_REMITTANCE","PAYER_DENIAL_LETTER","PAYER_RESPONSE","OTHER"]},"documentName":{"type":"string"},"status":{"type":"string","enum":["REQUIRED","REQUESTED","IN_PROGRESS","UPLOADED","REVIEWED","APPROVED","REJECTED_REDO"]},"fileId":{"type":["string","null"]},"dueDate":{"type":["string","null"],"format":"date-time"},"uploadedAt":{"type":["string","null"],"format":"date-time"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewNotes":{"type":["string","null"]},"isRequired":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"file":{"type":["object","null"],"properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","filename","mimeType","sizeBytes","createdAt","updatedAt"]}},"required":["id","appealId","documentType","documentName","status","fileId","dueDate","uploadedAt","reviewedAt","reviewNotes","isRequired","createdAt","updatedAt","file"]}},"required":["document"]}},"required":["success","data"]},"example":{"success":true,"data":{"document":{"id":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","documentType":"APPEAL_LETTER","documentName":"Example appeal_document_statu","status":"REQUIRED","fileId":"00000000-0000-4000-8000-000000000001","dueDate":"2026-06-08T10:15:30Z","uploadedAt":"2026-06-08T10:15:30Z","reviewedAt":"2026-06-08T10:15:30Z","reviewNotes":"Example appeal_document_statu note","isRequired":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","file":{"id":"00000000-0000-4000-8000-000000000001","filename":"Example appeal_document_statu","mimeType":"example-mimetype","sizeBytes":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Concurrent document status update conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/appeals/{appealId}/packet/compile":{"post":{"operationId":"compileAppealPacket","summary":"Compile appeal packet","description":"Compiles an appeal packet workflow and records storage state without returning storage keys.\n\n### When to use\nUse this after all required supporting documents have files linked and the appeal packet is ready for local packet assembly.\n\n### Before calling\nList documents and confirm each required document has a linked file.\n\n### Request guidance\nPass the appeal id in the path. The optional `note` is accepted by the schema but the current handler primarily uses the appeal id.\n\n### Request notes\n- Compile only after upload/link workflows are complete.\n- Do not expect the response to contain a raw S3 key.\n\n### Response semantics\nThe response returns `status: COMPILED` and `storage: S3_KEY_RECORDED`; it does not return the packet storage key or a direct packet download URL.\n\n### Response notes\n- `storage: S3_KEY_RECORDED` means storage metadata was recorded internally.\n- Use document download endpoints for individual supporting files.\n\n### Errors and retries\n400 can mean documents are missing linked files. After timeouts, inspect appeal activities or document state before retrying packet compilation.\n\n### Error notes\n- 404 means the appeal is missing or inaccessible.\n- 400 means packet readiness validation failed.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional compile note accepted by the schema; avoid PHI, credentials, and raw payer payloads."}}},"example":{"note":"Example compile_appeal_packet note"}}},"description":"Pass the appeal id in the path. The optional `note` is accepted by the schema but the current handler primarily uses the appeal id."},"responses":{"200":{"description":"Appeal packet compiled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appealId":{"type":"string"},"status":{"type":"string","enum":["COMPILED"]},"storage":{"type":"string","enum":["S3_KEY_RECORDED"]}},"required":["appealId","status","storage"]}},"required":["success","data"]},"example":{"success":true,"data":{"appealId":"00000000-0000-4000-8000-000000000001","status":"COMPILED","storage":"S3_KEY_RECORDED"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/{appealId}/deadlines":{"post":{"operationId":"setAppealDeadline","summary":"Set appeal deadline","description":"Sets or extends the deadline for an organization-owned appeal.\n\n### When to use\nUse this when payer rules, extension approval, or internal review changes the appeal due date.\n\n### Before calling\nConfirm the new deadline is in the future and supported by operational evidence.\n\n### Request guidance\nSend a future ISO datetime in `deadline` and optional `note` explaining the change.\n\n### Request notes\n- `deadline` must be a valid future ISO datetime.\n- Use `note` to capture extension context without payer secrets.\n\n### Response semantics\nThe response returns the updated appeal with the new deadline.\n\n### Response notes\n- Returned appeal includes the updated appealDeadline.\n- An activity is recorded internally.\n\n### Errors and retries\n400 means the deadline is invalid or not in the future. Re-read appeal state after 409 conflicts.\n\n### Error notes\n- 404 means the appeal is missing or inaccessible.\n- 409 means concurrent appeal update conflict.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"Tenant-scoped local appeal identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deadline":{"type":"string","format":"date-time","description":"Future ISO datetime for the appeal deadline."},"note":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional note explaining deadline context or extension basis; avoid credentials and raw payer messages."}},"required":["deadline"]},"example":{"deadline":"2026-06-08T10:15:30Z","note":"Example set_appeal_deadline note"}}},"description":"Send a future ISO datetime in `deadline` and optional `note` explaining the change."},"responses":{"200":{"description":"Appeal deadline updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string","enum":["LEVEL_1_RECONSIDERATION","LEVEL_2_FORMAL_APPEAL","LEVEL_3_EXTERNAL_REVIEW","LEVEL_4_ALJ_HEARING","LEVEL_5_COUNCIL_REVIEW","LEVEL_6_FEDERAL_COURT","STATE_FAIR_HEARING","INDEPENDENT_REVIEW_ORG","STATE_INSURANCE_DEPT"]},"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"]},"outcome":{"type":["string","null"],"enum":["FULL_OVERTURN","PARTIAL_OVERTURN","UPHELD","DISMISSED_PROCEDURAL","WITHDRAWN_BY_PROVIDER","SETTLED","NO_RESPONSE_DEFAULT"]},"submissionMethod":{"type":["string","null"],"enum":["ELECTRONIC_PORTAL","FAX","MAIL_CERTIFIED","MAIL_REGULAR","EDI_277","PHONE_VERBAL"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"payerDecisionDate":{"type":["string","null"],"format":"date-time"},"totalAppealedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"submittedAt":{"type":["string","null"],"format":"date-time"},"confirmationNumber":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"denialCaseSummary":{"type":["object","null"],"properties":{"caseNumber":{"type":["string","null"]},"claimNumber":{"type":["string","null"]},"payerName":{"type":["string","null"]},"denialReason":{"type":["string","null"]},"primaryCode":{"type":["string","null"]},"denialDate":{"type":["string","null"],"format":"date-time"}},"required":["caseNumber","claimNumber","payerName","denialReason","primaryCode","denialDate"]}},"required":["id","organizationId","denialCaseId","claimId","level","status","outcome","submissionMethod","appealDeadline","payerDecisionDate","totalAppealedAmount","totalRecoveredAmount","submittedAt","confirmationNumber","trackingNumber","createdAt","updatedAt","denialCaseSummary"]}},"required":["appeal"]}},"required":["success","data"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"LEVEL_1_RECONSIDERATION","status":"DRAFT","outcome":"FULL_OVERTURN","submissionMethod":"ELECTRONIC_PORTAL","appealDeadline":"2026-06-08T10:15:30Z","payerDecisionDate":"2026-06-08T10:15:30Z","totalAppealedAmount":"example-totalappealedamount","totalRecoveredAmount":"example-totalrecoveredamount","submittedAt":"2026-06-08T10:15:30Z","confirmationNumber":"example-confirmationnumber","trackingNumber":"example-trackingnumber","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","denialCaseSummary":{"caseNumber":"example-casenumber","claimNumber":"example-claimnumber","payerName":"Example set_appeal_deadline","denialReason":"example-denialreason","primaryCode":"example-primarycode","denialDate":"2026-06-08T10:15:30Z"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Concurrent appeal update conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/appeals/deadlines/upcoming":{"get":{"operationId":"getAppealUpcomingDeadlines","summary":"Get upcoming appeal deadlines","description":"Returns upcoming and overdue active appeal deadline data for the authenticated organization.\n\n### When to use\nUse this to build deadline widgets, reminder checks, or operational alerts.\n\n### Before calling\nChoose `daysAhead` based on the alert horizon your integration needs.\n\n### Request guidance\n`daysAhead` is optional and must be between 1 and 365 when provided.\n\n### Request notes\n- Use this endpoint for summary/alert workflows rather than full appeal details.\n- Call getAppeal for detail on a specific appeal.\n\n### Response semantics\nCurrent implementation returns serialized deadline summary data with top-level `total`, `overdue`, `dueSoon`, and `items`. The OpenAPI response schema remains generic, so clients should still guard report-shaped data defensively.\n\n### Response notes\n- Overdue appeals are included when their deadline is before now and still active.\n- Generic response shape may require client-side schema guards.\n\n### Errors and retries\nTreat invalid daysAhead values as 400. Back off on 429 for scheduled polling.\n\n### Error notes\n- 400 means daysAhead failed validation.\n- 429 should be retried with backoff.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":365},"required":false,"name":"daysAhead","in":"query","description":"Number of days ahead to include in the deadline window."}],"responses":{"200":{"description":"Upcoming appeal deadlines","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"]},"example":{"success":true,"data":"example-data"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/deadlines/overdue":{"get":{"operationId":"getOverdueAppeals","summary":"Get overdue appeals","description":"Returns active appeals whose deadlines are already past due for the authenticated organization.\n\n### When to use\nUse this for overdue appeal queues, escalations, and compliance cleanup workflows.\n\n### Before calling\nChoose pagination bounds and decide whether the client should fetch full appeal details separately.\n\n### Request guidance\nUse `skip` and `take`; the operation orders overdue items by appeal deadline.\n\n### Request notes\n- Use pagination for large overdue queues.\n- Terminal appeal statuses are excluded by the implementation.\n- `skip` is the zero-based offset for overdue appeal results.\n- `take` controls page size and is capped at 100.\n\n### Response semantics\nCurrent implementation returns serialized overdue data with top-level `items`, `total`, and `isTruncated`. The OpenAPI response schema remains generic, so clients should still guard response data defensively.\n\n### Response notes\n- Items include deadline and daysRemaining-style urgency context.\n- Use getAppeal for full detail.\n\n### Errors and retries\nTreat invalid pagination as 400. Back off on 429 if polling overdue queues.\n\n### Error notes\n- 400 means pagination validation failed.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000},"required":false,"name":"skip","in":"query","description":"Zero-based pagination offset for overdue appeal results; valid range is 0 through 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"take","in":"query","description":"Page size for overdue appeal results; valid range is 1 through 100."}],"responses":{"200":{"description":"Overdue appeals","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"]},"example":{"success":true,"data":"example-data"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/reminders/{reminderId}/acknowledge":{"post":{"operationId":"acknowledgeAppealReminder","summary":"Acknowledge appeal reminder","description":"Acknowledges an organization-scoped appeal reminder.\n\n### When to use\nUse this after a staff member or integration has handled a deadline reminder.\n\n### Before calling\nResolve the `reminderId` from QuickRCM reminder or deadline data.\n\n### Request guidance\nPass the path reminder id and an empty JSON body.\n\n### Request notes\n- Use reminder IDs from QuickRCM responses.\n- No note field is currently accepted.\n\n### Response semantics\nThe response wraps the serialized reminder in `data.reminder`. The implementation marks the reminder as triggered/acknowledged with a timestamp.\n\n### Response notes\n- Returned reminder data is serialized generically.\n- Acknowledgment is local workflow state.\n\n### Errors and retries\nAfter a timeout, re-read reminder or deadline state before retrying.\n\n### Error notes\n- 404 means the reminder is missing or inaccessible.\n- 400 means request validation failed.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"reminderId","in":"path","description":"QuickRCM appeal reminder identifier."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"Pass the path reminder id and an empty JSON body."},"responses":{"200":{"description":"Appeal reminder acknowledged","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"]},"example":{"success":true,"data":"example-data"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Reminder not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/compliance-scan":{"post":{"operationId":"runAppealComplianceScan","summary":"Run appeal compliance scan","description":"Runs local appeal compliance checks and creates compliance event rows for detected issues.\n\n### When to use\nUse this for controlled administrative or scheduled checks when you need QuickRCM to inspect current appeal deadline compliance.\n\n### Before calling\nDecide whether to scan all active appeals or one appeal via `appealId`. Ensure the API key has write scope.\n\n### Request guidance\nSend an empty body for an organization-wide scan or an `appealId` to target one appeal.\n\n### Request notes\n- Use targeted `appealId` scans when possible.\n- This is a local compliance workflow, not legal advice or a guarantee of regulatory completeness.\n\n### Response semantics\nCurrent implementation reports `scanned`, `violationsFound`, `eventsCreated`, and sanitized `violations`. It creates APPEAL_DEADLINE_MISSED events for active appeals that missed deadlines and avoids duplicate unresolved events.\n\n### Response notes\n- `eventsCreated` may be less than `violationsFound` when unresolved duplicate events already exist.\n- Violation details are intentionally limited.\n\n### Errors and retries\nDo not run tight retry loops. If a scan times out, list compliance events before rerunning to avoid duplicate operational work.\n\n### Error notes\n- 400 means request validation failed.\n- 429 should be retried with backoff.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"appealId":{"type":"string","minLength":1,"description":"Optional tenant-scoped local appeal identifier used to target one appeal; omit to scan active appeals for the authenticated organization."}}},"example":{"appealId":"00000000-0000-4000-8000-000000000001"}}},"description":"Send an empty body for an organization-wide scan or an `appealId` to target one appeal."},"responses":{"200":{"description":"Appeal compliance scan result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"]},"example":{"success":true,"data":"example-data"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/compliance-reports/payer":{"get":{"operationId":"getAppealPayerComplianceReport","summary":"Get appeal payer compliance report","description":"Returns payer-focused appeal compliance report data for the authenticated organization.\n\n### When to use\nUse this to evaluate compliance trends by payer, payer id, payer name, and date window.\n\n### Before calling\nChoose payer filters and date bounds that match the report audience.\n\n### Request guidance\nUse `payerId` when you have QuickRCM payer configuration identity; use `payerName` for name-based filtering.\n\n### Request notes\n- Use a date range for stable period-over-period reporting.\n- Avoid placing PHI in payerName filters.\n\n### Response semantics\nThe response wraps serialized report data in `data.report`. The report body is implementation-shaped and based on local QuickRCM compliance event records.\n\n### Response notes\n- `report` is serialized report data.\n- Compliance reporting is based on local QuickRCM event records.\n\n### Errors and retries\nTreat invalid dates or payer-name length issues as 400. Back off on 429 for scheduled reporting.\n\n### Error notes\n- 400 means query validation failed.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time"},"required":false,"name":"startDate","in":"query","description":"Optional lower ISO datetime bound for the payer compliance report period."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"endDate","in":"query","description":"Optional upper ISO datetime bound for the payer compliance report period."},{"schema":{"type":"string","minLength":1},"required":false,"name":"payerId","in":"query","description":"QuickRCM payer configuration identifier."},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"payerName","in":"query","description":"Payer name filter for the report."}],"responses":{"200":{"description":"Appeal payer compliance report","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"]},"example":{"success":true,"data":"example-data"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/appeals/compliance-events/{eventId}/resolve":{"put":{"operationId":"resolveAppealComplianceEvent","summary":"Resolve appeal compliance event","description":"Marks an appeal compliance event as resolved.\n\n### When to use\nUse this after staff have addressed the compliance event or determined the event no longer requires action.\n\n### Before calling\nRead the event and confirm resolution notes are appropriate for audit history.\n\n### Request guidance\nPass `eventId` in the path and optional `resolutionNotes` in the body.\n\n### Request notes\n- `resolutionNotes` is optional but useful for audit context.\n- Avoid legal conclusions beyond the verified operational resolution.\n\n### Response semantics\nThe response returns the resolved compliance event with resolution fields. When linked to an appeal, an appeal activity is recorded internally.\n\n### Response notes\n- `isResolved` is true after success.\n- `resolvedBy` is the authenticated synthetic user context for the API key.\n\n### Errors and retries\nAfter timeouts, read the compliance event before retrying to avoid duplicate operational notes.\n\n### Error notes\n- 404 means the compliance event is missing or inaccessible.\n- 400 means request validation failed.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"eventId","in":"path","description":"Tenant-scoped QuickRCM appeal compliance event identifier selected from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolutionNotes":{"type":"string","minLength":1,"maxLength":4000,"description":"Optional notes explaining how the compliance event was resolved."}}},"example":{"resolutionNotes":"Example appeal_compliance_event note"}}},"description":"Pass `eventId` in the path and optional `resolutionNotes` in the body."},"responses":{"200":{"description":"Appeal compliance event resolved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"complianceEvent":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"appealId":{"type":["string","null"]},"eventType":{"type":"string"},"severity":{"type":["string","null"]},"regulation":{"type":["string","null"]},"jurisdictionState":{"type":["string","null"]},"payerType":{"type":["string","null"]},"description":{"type":["string","null"]},"deadlineDate":{"type":["string","null"],"format":"date-time"},"actualDate":{"type":["string","null"],"format":"date-time"},"daysVariance":{"type":["integer","null"]},"isResolved":{"type":"boolean"},"resolvedBy":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolutionAction":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","appealId","eventType","severity","regulation","jurisdictionState","payerType","description","deadlineDate","actualDate","daysVariance","isResolved","resolvedBy","resolvedAt","resolutionAction","createdAt"]}},"required":["complianceEvent"]}},"required":["success","data"]},"example":{"success":true,"data":{"complianceEvent":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","eventType":"example-eventtype","severity":"example-severity","regulation":"example-regulation","jurisdictionState":"example-jurisdictionstate","payerType":"example-payertype","description":"Example appeal_compliance_event note","deadlineDate":"2026-06-08T10:15:30Z","actualDate":"2026-06-08T10:15:30Z","daysVariance":1,"isResolved":true,"resolvedBy":"example-resolvedby","resolvedAt":"2026-06-08T10:15:30Z","resolutionAction":"example-resolutionaction","createdAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Compliance event not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/appeals/compliance-events/{eventId}":{"get":{"operationId":"getAppealComplianceEvent","summary":"Get appeal compliance event","description":"Returns one appeal compliance event owned by the authenticated organization.\n\n### When to use\nUse this after a compliance queue item or list response provides an `eventId`.\n\n### Before calling\nConfirm the event id came from QuickRCM under the same organization.\n\n### Request guidance\nPass only the event id path parameter.\n\n### Request notes\n- Use event ids returned by listAppealComplianceEvents.\n- No query parameters are required.\n\n### Response semantics\nThe response returns sanitized compliance event fields and omits internal metadata.\n\n### Response notes\n- The event may or may not be linked to an appeal.\n- Resolution fields are populated after resolveAppealComplianceEvent.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization event context.\n\n### Error notes\n- 404 means the event is missing or inaccessible.\n- 401/403 require credential or scope correction.\n","tags":["Appeals"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"eventId","in":"path","description":"Tenant-scoped QuickRCM appeal compliance event identifier selected from the path."}],"responses":{"200":{"description":"Appeal compliance event","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"complianceEvent":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"appealId":{"type":["string","null"]},"eventType":{"type":"string"},"severity":{"type":["string","null"]},"regulation":{"type":["string","null"]},"jurisdictionState":{"type":["string","null"]},"payerType":{"type":["string","null"]},"description":{"type":["string","null"]},"deadlineDate":{"type":["string","null"],"format":"date-time"},"actualDate":{"type":["string","null"],"format":"date-time"},"daysVariance":{"type":["integer","null"]},"isResolved":{"type":"boolean"},"resolvedBy":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolutionAction":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","appealId","eventType","severity","regulation","jurisdictionState","payerType","description","deadlineDate","actualDate","daysVariance","isResolved","resolvedBy","resolvedAt","resolutionAction","createdAt"]}},"required":["complianceEvent"]}},"required":["success","data"]},"example":{"success":true,"data":{"complianceEvent":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","appealId":"00000000-0000-4000-8000-000000000001","eventType":"example-eventtype","severity":"example-severity","regulation":"example-regulation","jurisdictionState":"example-jurisdictionstate","payerType":"example-payertype","description":"Example appeal_compliance_event note","deadlineDate":"2026-06-08T10:15:30Z","actualDate":"2026-06-08T10:15:30Z","daysVariance":1,"isResolved":true,"resolvedBy":"example-resolvedby","resolvedAt":"2026-06-08T10:15:30Z","resolutionAction":"example-resolutionaction","createdAt":"2026-06-08T10:15:30Z"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Compliance event not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/work-queues":{"get":{"operationId":"listArWorkQueues","summary":"List AR work queues","description":"Lists non-deleted Accounts Receivable work queues owned by the authenticated organization.\n\n### When to use\nUse this to populate AR queue selectors, operational dashboards, or integration routing logic.\n\n### Before calling\nAuthenticate with the tenant API key and decide whether inactive queues should be included.\n\n### Request guidance\nUse pagination parameters where available and avoid assuming queue names are globally unique.\n\n### Request notes\n- Use activeOnly when building user-facing queue pickers.\n- Use pagination for large organizations.\n\n### Response semantics\nThe response returns local queue configuration, not individual claim or patient-account work items.\n\n### Response notes\n- Queues are local routing containers.\n- Items are retrieved with listArWorkQueueItems.\n\n### Errors and retries\nTreat authorization failures as API-key or scope issues and retry only transient 5xx or 429 responses.\n\n### Error notes\n- 429 requires backoff.\n- 403 means the key lacks access to AR queues.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query","description":"Maximum number of records to return. Use bounded pagination and avoid unbounded exports."},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query","description":"Zero-based offset for paginated list requests."}],"responses":{"200":{"description":"AR work queues for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"workQueues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"queueType":{"type":["string","null"]},"slaHours":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","name","description","queueType","slaHours","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"]}},"required":["workQueues","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"workQueues":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example ar_work_queue","description":"Example ar_work_queue note","queueType":"example-queuetype","slaHours":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"pagination":{"total":1,"limit":1,"offset":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}},"post":{"operationId":"createArWorkQueue","summary":"Create AR work queue","description":"Creates a local Accounts Receivable work queue for organizing payer follow-up, patient balance, denial, collection, or appeal work.\n\n### When to use\nUse this when onboarding a new AR workflow lane or segmenting teams by payer, priority, balance type, or follow-up category.\n\n### Before calling\nChoose a clear queue name and queueType. Set slaHours only if your organization uses SLA-based routing.\n\n### Request guidance\nKeep descriptions operational and avoid PHI. Queue configuration is tenant-scoped and reusable.\n\n### Request notes\n- Use queueType to classify the queue.\n- Use slaHours only for real operational commitments.\n\n### Response semantics\nA successful response creates a queue container. It does not create work items or contact payers.\n\n### Response notes\n- Returns the created local queue.\n- Work items are created separately.\n\n### Errors and retries\nCorrect duplicate or invalid queue metadata before retrying. Avoid creating duplicate queues after network timeouts without checking listArWorkQueues.\n\n### Error notes\n- 400 means invalid queue metadata.\n- Retry network failures only after checking whether the queue was created.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Human-readable name for the queue, template, person, payer, or workflow object."},"description":{"type":"string","maxLength":2000,"description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"queueType":{"type":"string","minLength":1,"maxLength":100,"description":"Queue classification used to route AR work, such as payer follow-up, denial, patient balance, or appeal support."},"slaHours":{"type":"integer","minimum":1,"maximum":720,"description":"Service-level target in hours for a work queue or item. Use positive values that match operational policy."}},"required":["name"]},"example":{"name":"Example ar_work_queue","description":"Example ar_work_queue note","queueType":"example-queuetype","slaHours":1}}},"description":"Keep descriptions operational and avoid PHI. Queue configuration is tenant-scoped and reusable."},"responses":{"201":{"description":"Created AR work queue.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"workQueue":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"queueType":{"type":["string","null"]},"slaHours":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","name","description","queueType","slaHours","createdAt","updatedAt"]}},"required":["workQueue"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"workQueue":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example ar_work_queue","description":"Example ar_work_queue note","queueType":"example-queuetype","slaHours":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}}},"/api/v1/ar-management/work-queue-items":{"get":{"operationId":"listArWorkQueueItems","summary":"List AR work queue items","description":"Lists Accounts Receivable work items for the authenticated organization with optional queue, status, priority, and pagination filters.\n\n### When to use\nUse this to power AR worklists, staff dashboards, aging follow-up views, or integration reconciliation.\n\n### Before calling\nResolve queueId only when filtering to a specific queue; otherwise use status and priority filters to narrow work.\n\n### Request guidance\nUse bounded pagination and avoid broad PHI-heavy exports. Search terms should not be logged with raw PHI.\n\n### Request notes\n- Use queueId when driving a queue-specific page.\n- Use status and priority to avoid oversized lists.\n\n### Response semantics\nThe response returns local AR work items and assignment context, not direct payer communication evidence.\n\n### Response notes\n- Items are local work objects.\n- Follow-up history is created through createArFollowUp.\n\n### Errors and retries\nBack off on 429 and treat invalid filters as caller-side errors.\n\n### Error notes\n- 400 indicates invalid filter values.\n- 403 indicates missing AR access.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":false,"name":"workQueueId","in":"query","description":"QuickRCM AR work queue identifier. New work items must reference a queue owned by the organization."},{"schema":{"type":"string","enum":["WQI_OPEN","WQI_IN_PROGRESS","WQI_ESCALATED","WQI_RESOLVED"]},"required":false,"name":"status","in":"query","description":"Workflow status filter or target status. Valid values depend on the endpoint schema and module state machine."},{"schema":{"type":"string","enum":["CRITICAL","HIGH","MEDIUM","LOW"]},"required":false,"name":"priority","in":"query","description":"Work priority such as low, normal, high, urgent, or module-specific enum values."},{"schema":{"type":"boolean","default":true},"required":false,"name":"activeOnly","in":"query","description":"Boolean filter that limits list results to records still considered active for workflow use."},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query","description":"Maximum number of records to return. Use bounded pagination and avoid unbounded exports."},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query","description":"Zero-based offset for paginated list requests."}],"responses":{"200":{"description":"AR work queue items for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"workQueueId":{"type":"string"},"claimId":{"type":["string","null"]},"assignedToId":{"type":["string","null"]},"status":{"type":"string","enum":["WQI_OPEN","WQI_IN_PROGRESS","WQI_ESCALATED","WQI_RESOLVED"]},"priority":{"type":["string","null"]},"slaStatus":{"type":["string","null"]},"slaDeadline":{"type":["string","null"],"format":"date-time"},"firstTouchedAt":{"type":["string","null"],"format":"date-time"},"lastTouchedAt":{"type":["string","null"],"format":"date-time"},"touchCount":{"type":"integer"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"workQueue":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"queueType":{"type":["string","null"]}},"required":["id","name","queueType"]},"claim":{"type":["object","null"],"properties":{"id":{"type":"string"},"claimControlNumber":{"type":["string","null"]},"status":{"type":["string","null"]},"totalCharges":{"type":["string","null"]},"totalPaid":{"type":["string","null"]},"totalAdjusted":{"type":["string","null"]}},"required":["id","claimControlNumber","status","totalCharges","totalPaid","totalAdjusted"]}},"required":["id","organizationId","workQueueId","claimId","assignedToId","status","priority","slaStatus","slaDeadline","firstTouchedAt","lastTouchedAt","touchCount","resolvedAt","createdAt","updatedAt","workQueue","claim"]}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"]}},"required":["items","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"items":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","workQueueId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","assignedToId":"00000000-0000-4000-8000-000000000001","status":"WQI_OPEN","priority":"example-priority","slaStatus":"example-slastatus","slaDeadline":"2026-06-08T10:15:30Z","firstTouchedAt":"2026-06-08T10:15:30Z","lastTouchedAt":"2026-06-08T10:15:30Z","touchCount":1,"resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","workQueue":{"id":"00000000-0000-4000-8000-000000000001","name":"Example ar_work_queue_item","queueType":"example-queuetype"},"claim":{"id":"00000000-0000-4000-8000-000000000001","claimControlNumber":"example-claimcontrolnumber","status":"queued","totalCharges":"example-totalcharges","totalPaid":"00000000-0000-4000-8000-000000000001","totalAdjusted":"example-totaladjusted"}}],"pagination":{"total":1,"limit":1,"offset":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested AR work queue was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}},"post":{"operationId":"createArWorkQueueItem","summary":"Create AR work queue item","description":"Creates a local AR work queue item after verifying queue, claim, and assignee ownership.\n\n### When to use\nUse this to place a claim or AR task into a queue for staff action, automation follow-up, or team routing.\n\n### Before calling\nResolve workQueueId and optional claimId or assignedToId from the same tenant. Decide priority before queue placement.\n\n### Request guidance\nUse notes for staff context only. Do not embed payer portal credentials, raw EDI, or unnecessary PHI.\n\n### Request notes\n- workQueueId is required and must belong to the organization.\n- claimId and assignedToId are optional but must be tenant-owned when supplied.\n\n### Response semantics\nA successful response creates a local task-like AR item. It does not contact a payer or update claim adjudication.\n\n### Response notes\n- Returns the created local work item.\n- Follow-up and status updates are separate actions.\n\n### Errors and retries\nFix wrong-tenant queue, claim, or assignee identifiers before retrying. Check for duplicates after network failures.\n\n### Error notes\n- 404 can mean a referenced queue, claim, or user is unavailable to this tenant.\n- 400 means the item payload is invalid.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workQueueId":{"type":"string","minLength":1,"description":"QuickRCM AR work queue identifier. New work items must reference a queue owned by the organization."},"claimId":{"type":"string","minLength":1,"description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."},"assignedToId":{"type":"string","minLength":1,"description":"QuickRCM user identifier for the staff member assigned to the work item. The assignee must belong to the same organization."},"priority":{"type":"string","enum":["CRITICAL","HIGH","MEDIUM","LOW"],"default":"MEDIUM","description":"Work priority such as low, normal, high, urgent, or module-specific enum values."},"notes":{"type":"string","maxLength":10000,"description":"Human-readable note for staff context. Keep it concise and avoid secrets, raw EDI, and unnecessary PHI."}},"required":["workQueueId"]},"example":{"workQueueId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","assignedToId":"00000000-0000-4000-8000-000000000001","priority":"MEDIUM","notes":"Example ar_work_queue_item note"}}},"description":"Use notes for staff context only. Do not embed payer portal credentials, raw EDI, or unnecessary PHI."},"responses":{"201":{"description":"Created AR work queue item.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"}},"required":["id","organizationId"]}},"required":["item"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"item":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Work queue or claim was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/work-queues/{queueId}":{"put":{"operationId":"updateArWorkQueue","summary":"Update AR work queue","description":"Updates local configuration for an organization-scoped Accounts Receivable work queue.\n\n### When to use\nUse this when renaming a queue, changing its description, adjusting queueType, or updating the SLA target.\n\n### Before calling\nLoad the current queue and make sure users or automations relying on the queue understand the configuration change.\n\n### Request guidance\nSend operational metadata only. Avoid PHI in queue names or descriptions because queues are reusable containers.\n\n### Request notes\n- queueId selects the queue in the path.\n- Descriptions should be operational rather than patient-specific.\n\n### Response semantics\nThe response returns the updated queue configuration. Existing items remain separate records.\n\n### Response notes\n- Returns the updated local queue.\n- Does not bulk-change existing item status.\n\n### Errors and retries\nRetry transient failures only after checking whether the update was applied; repeated updates can overwrite concurrent admin changes.\n\n### Error notes\n- 404 can mean missing or wrong-tenant queue.\n- 409-style conflicts should be treated as stale admin state when exposed.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"queueId","in":"path","description":"QuickRCM AR work queue identifier used in the path or filter. It must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Human-readable name for the queue, template, person, payer, or workflow object."},"description":{"type":"string","maxLength":2000,"description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"queueType":{"type":"string","minLength":1,"maxLength":100,"description":"Queue classification used to route AR work, such as payer follow-up, denial, patient balance, or appeal support."},"slaHours":{"type":"integer","minimum":1,"maximum":720,"description":"Service-level target in hours for a work queue or item. Use positive values that match operational policy."}}},"example":{"name":"Example ar_work_queue","description":"Example ar_work_queue note","queueType":"example-queuetype","slaHours":1}}},"description":"Send operational metadata only. Avoid PHI in queue names or descriptions because queues are reusable containers."},"responses":{"200":{"description":"Updated AR work queue.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"workQueue":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"queueType":{"type":["string","null"]},"slaHours":{"type":["integer","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","name","description","queueType","slaHours","createdAt","updatedAt"]}},"required":["workQueue"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"workQueue":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example ar_work_queue","description":"Example ar_work_queue note","queueType":"example-queuetype","slaHours":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"AR work queue not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/work-queue-items/bulk-assignment":{"put":{"operationId":"bulkAssignArWorkQueueItems","summary":"Bulk assign AR work queue items","description":"Assigns multiple AR work queue items to a tenant user after checking membership and item ownership.\n\n### When to use\nUse this for workload balancing, supervisor assignment, team handoff, or daily AR queue distribution.\n\n### Before calling\nCollect itemIds from listArWorkQueueItems and verify the assignee is an active member of the same organization.\n\n### Request guidance\nKeep batches bounded. If one item fails validation, handle partial-failure semantics according to the response contract.\n\n### Request notes\n- itemIds should all come from the same tenant.\n- assignedToId must reference a valid organization member.\n\n### Response semantics\nA successful response updates local assignment metadata; it does not change payer status or perform follow-up.\n\n### Response notes\n- Returns assignment results or updated item context.\n- No payer communication is performed.\n\n### Errors and retries\nRe-read affected items after a timeout before retrying to avoid repeated assignment churn.\n\n### Error notes\n- 400 means itemIds or assignedToId are invalid.\n- 404 can mean at least one work item is unavailable to this tenant.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"itemIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":200,"description":"Array of AR work queue item identifiers selected for a bulk action."},"assignedToId":{"type":"string","minLength":1,"description":"QuickRCM user identifier for the staff member assigned to the work item. The assignee must belong to the same organization."}},"required":["itemIds","assignedToId"]},"example":{"itemIds":["example-itemids"],"assignedToId":"00000000-0000-4000-8000-000000000001"}}},"description":"Keep batches bounded. If one item fails validation, handle partial-failure semantics according to the response contract."},"responses":{"200":{"description":"Bulk assignment result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"updatedCount":{"type":"integer"}},"required":["updatedCount"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"updatedCount":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"One or more AR work queue items were not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/work-queue-items/{itemId}/status":{"put":{"operationId":"updateArWorkQueueItemStatus","summary":"Update AR work queue item status","description":"Updates the status of a local AR work queue item and writes an AR audit entry.\n\n### When to use\nUse this when staff or automation moves an AR item through open, in-progress, waiting, escalated, completed, or similar workflow states.\n\n### Before calling\nLoad the item, decide the targetStatus, and include notes when the transition needs audit context.\n\n### Request guidance\nUse valid workflow statuses only. Keep notes concise and PHI-minimal.\n\n### Request notes\n- targetStatus is the requested new state.\n- notes explain why the transition happened.\n\n### Response semantics\nThe response reflects local workflow status and audit capture. It does not imply payer action.\n\n### Response notes\n- Returns updated local item state.\n- Audit history is local QuickRCM evidence.\n\n### Errors and retries\nDo not blindly retry status transitions after timeouts; re-read the item to avoid duplicate audit noise.\n\n### Error notes\n- 400 means invalid target status or transition context.\n- 404 means the itemId is missing or wrong tenant.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"itemId","in":"path","description":"QuickRCM AR work queue item identifier. It must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["WQI_OPEN","WQI_IN_PROGRESS","WQI_ESCALATED","WQI_RESOLVED"],"description":"Workflow status filter or target status. Valid values depend on the endpoint schema and module state machine."},"escalationReason":{"type":"string","minLength":1,"maxLength":2000,"description":"Reason the work item or account moved to a higher-priority AR or collection path."},"managerId":{"type":"string","minLength":1,"description":"QuickRCM user identifier for the manager or reviewer associated with the workflow."}},"required":["status"]},"example":{"status":"WQI_OPEN","escalationReason":"example-escalationreason","managerId":"00000000-0000-4000-8000-000000000001"}}},"description":"Use valid workflow statuses only. Keep notes concise and PHI-minimal."},"responses":{"200":{"description":"Updated AR work queue item.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"workQueueId":{"type":"string"},"claimId":{"type":["string","null"]},"assignedToId":{"type":["string","null"]},"status":{"type":"string","enum":["WQI_OPEN","WQI_IN_PROGRESS","WQI_ESCALATED","WQI_RESOLVED"]},"priority":{"type":["string","null"]},"slaStatus":{"type":["string","null"]},"slaDeadline":{"type":["string","null"],"format":"date-time"},"firstTouchedAt":{"type":["string","null"],"format":"date-time"},"lastTouchedAt":{"type":["string","null"],"format":"date-time"},"touchCount":{"type":"integer"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"workQueue":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"queueType":{"type":["string","null"]}},"required":["id","name","queueType"]},"claim":{"type":["object","null"],"properties":{"id":{"type":"string"},"claimControlNumber":{"type":["string","null"]},"status":{"type":["string","null"]},"totalCharges":{"type":["string","null"]},"totalPaid":{"type":["string","null"]},"totalAdjusted":{"type":["string","null"]}},"required":["id","claimControlNumber","status","totalCharges","totalPaid","totalAdjusted"]}},"required":["id","organizationId","workQueueId","claimId","assignedToId","status","priority","slaStatus","slaDeadline","firstTouchedAt","lastTouchedAt","touchCount","resolvedAt","createdAt","updatedAt","workQueue","claim"]}},"required":["item"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"item":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","workQueueId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","assignedToId":"00000000-0000-4000-8000-000000000001","status":"WQI_OPEN","priority":"example-priority","slaStatus":"example-slastatus","slaDeadline":"2026-06-08T10:15:30Z","firstTouchedAt":"2026-06-08T10:15:30Z","lastTouchedAt":"2026-06-08T10:15:30Z","touchCount":1,"resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","workQueue":{"id":"00000000-0000-4000-8000-000000000001","name":"Example ar_work_queue_item_statu","queueType":"example-queuetype"},"claim":{"id":"00000000-0000-4000-8000-000000000001","claimControlNumber":"example-claimcontrolnumber","status":"queued","totalCharges":"example-totalcharges","totalPaid":"00000000-0000-4000-8000-000000000001","totalAdjusted":"example-totaladjusted"}}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"AR work queue item not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"AR work queue item was modified concurrently.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/ar-management/follow-ups":{"post":{"operationId":"createArFollowUp","summary":"Create AR follow-up","description":"Records a payer, patient, agency, or internal AR follow-up and updates linked work queue touch metadata.\n\n### When to use\nUse this after staff or automation performs a phone, portal, fax, mail, or internal follow-up related to a claim.\n\n### Before calling\nResolve the claimId and optional workQueueItemId. Capture contact, outcome, next follow-up, and required action details.\n\n### Request guidance\nnotes is required and should summarize the interaction without raw payer payloads or excessive PHI.\n\n### Request notes\n- method describes the follow-up channel.\n- nextFollowUpDate and nextFollowUpReason schedule continued work.\n\n### Response semantics\nA successful response creates local follow-up evidence and may update local queue touch metadata. It does not send a payer message by itself.\n\n### Response notes\n- Creates local follow-up evidence.\n- May update work queue touch metadata.\n\n### Errors and retries\nIf a timeout occurs, check the claim follow-up history before retrying to avoid duplicate notes.\n\n### Error notes\n- 400 means required follow-up details are missing.\n- 404 means claimId or workQueueItemId is unavailable to this tenant.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimId":{"type":"string","minLength":1,"description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."},"workQueueItemId":{"type":"string","minLength":1,"description":"QuickRCM AR work queue item identifier. Use it to link follow-up, status, or audit activity to a work item."},"method":{"type":"string","minLength":1,"maxLength":80,"description":"Follow-up or correspondence channel, such as phone, portal, fax, mail, email, or internal note."},"outcome":{"type":"string","minLength":1,"maxLength":100,"description":"Result of an AR follow-up, correspondence, appeal, or collection action."},"contactName":{"type":"string","maxLength":200,"description":"Name of the payer, patient, agency, or internal contact reached during follow-up."},"contactTitle":{"type":"string","maxLength":200,"description":"Role or title for the follow-up contact, such as payer representative, supervisor, patient advocate, or billing lead."},"referenceNumber":{"type":"string","maxLength":200,"description":"Payer, call, portal, appeal, or correspondence reference number captured for reconciliation."},"callDurationMin":{"type":["integer","null"],"minimum":0,"description":"Duration of an AR follow-up call in whole minutes. Use null only when no duration was captured."},"notes":{"type":"string","minLength":1,"maxLength":10000,"description":"Human-readable note for staff context. Keep it concise and avoid secrets, raw EDI, and unnecessary PHI."},"internalNotes":{"type":"string","maxLength":5000,"description":"Internal staff-only note. Avoid credentials, raw payer payloads, raw EDI, and unnecessary PHI."},"actionRequired":{"type":"string","maxLength":2000,"description":"Follow-up action requested after the AR contact, such as resubmission, documentation, escalation, or a payer callback."},"nextFollowUpDate":{"type":"string","format":"date-time","description":"Date when the next AR follow-up should occur. Use an ISO date string."},"nextFollowUpReason":{"type":"string","maxLength":500,"description":"Reason the claim or account needs another follow-up cycle."}},"required":["claimId","method","notes"]},"example":{"claimId":"00000000-0000-4000-8000-000000000001","method":"example-method","notes":"Example ar_follow_up note","workQueueItemId":"00000000-0000-4000-8000-000000000001","outcome":"example-outcome","contactName":"Example ar_follow_up","contactTitle":"example-contacttitle","referenceNumber":"example-referencenumber","callDurationMin":1,"internalNotes":"Example ar_follow_up note","actionRequired":"example-actionrequired"}}},"description":"notes is required and should summarize the interaction without raw payer payloads or excessive PHI."},"responses":{"201":{"description":"Created AR follow-up.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"followUp":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"}},"required":["id","organizationId"]}},"required":["followUp"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"followUp":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim or work queue item was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/correspondence":{"post":{"operationId":"generateArCorrespondence","summary":"Generate AR correspondence","description":"Generates and stores local AR correspondence metadata and content without external delivery.\n\n### When to use\nUse this to prepare payer letters, patient balance communication, appeal support, or collection documentation before any send workflow.\n\n### Before calling\nChoose the recipient, subject, body or template, and related claim or patient-account context.\n\n### Request guidance\nKeep correspondence content sanitized. Do not include credentials, raw EDI, or unnecessary PHI in template variables.\n\n### Request notes\n- recipient fields identify the intended audience.\n- templateId and extraVars can render standardized content.\n\n### Response semantics\nThe response creates local correspondence. It is not proof that email, fax, mail, or portal delivery occurred.\n\n### Response notes\n- Stores correspondence locally.\n- Use sendArCorrespondence for queued or simulated send state.\n\n### Errors and retries\nAfter timeouts, list or inspect correspondence before generating another copy.\n\n### Error notes\n- 400 means content, recipient, or template data is invalid.\n- Do not retry blindly if duplicate letters would confuse staff.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimId":{"type":"string","minLength":1,"description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."},"templateId":{"type":"string","minLength":1,"description":"QuickRCM template identifier used to render correspondence or workflow text."},"type":{"type":"string","minLength":1,"maxLength":100,"description":"Type discriminator for the surrounding object, such as product type, provider type, queue type, or appeal type."},"method":{"type":"string","minLength":1,"maxLength":100,"description":"Follow-up or correspondence channel, such as phone, portal, fax, mail, email, or internal note."},"subject":{"type":"string","maxLength":500,"description":"Subject line for local correspondence. Avoid secrets and unnecessary PHI."},"body":{"type":"string","maxLength":50000,"description":"Message body for locally generated correspondence. Keep it payer-appropriate and avoid credentials, raw EDI, and excessive PHI."},"recipientName":{"type":"string","maxLength":200,"description":"Display name of the correspondence recipient, such as payer department, patient, guarantor, or agency."},"recipientFax":{"type":"string","maxLength":80,"description":"Fax destination for locally generated correspondence metadata. Validate formatting before external delivery is enabled."},"recipientAddress":{"type":"string","maxLength":1000,"description":"Mailing address for correspondence. Treat as sensitive and verify the recipient before use."},"recipientEmail":{"type":"string","maxLength":320,"format":"email","description":"Email destination for locally generated correspondence metadata. Do not include credentials or tokens."},"extraVars":{"type":"object","additionalProperties":{"type":"string"},"description":"Template variables or caller-supplied values used to render local correspondence. Do not include credentials."}},"required":["claimId","type","method"]},"example":{"claimId":"00000000-0000-4000-8000-000000000001","type":"example-type","method":"example-method","templateId":"00000000-0000-4000-8000-000000000001","subject":"example-subject","body":"example-body","recipientName":"Example ar_correspondence","recipientFax":"+15551234567","recipientAddress":"example-recipientaddress","recipientEmail":"developer@example.com","extraVars":{}}}},"description":"Keep correspondence content sanitized. Do not include credentials, raw EDI, or unnecessary PHI in template variables."},"responses":{"201":{"description":"Generated AR correspondence.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"correspondence":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"}},"required":["id","organizationId"]}},"required":["correspondence"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"correspondence":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim or template was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/correspondence/{correspondenceId}/send":{"put":{"operationId":"sendArCorrespondence","summary":"Queue AR correspondence send","description":"Records a queued or simulated send status for local AR correspondence without making a live external delivery call.\n\n### When to use\nUse this when the integration wants QuickRCM to mark correspondence as queued or ready for a delivery workflow.\n\n### Before calling\nVerify the correspondenceId belongs to the tenant and the content has been reviewed.\n\n### Request guidance\nUse dryRun or queueOnly where supported to avoid claiming external delivery before delivery channels are enabled.\n\n### Request notes\n- correspondenceId selects the local correspondence record.\n- Use queue controls to keep side effects safe.\n\n### Response semantics\nThe response reflects local queued or simulated send state. It is not proof of email, fax, mail, or portal delivery.\n\n### Response notes\n- Updates local correspondence state.\n- External delivery proof is not implied.\n\n### Errors and retries\nRe-read correspondence state after timeouts before retrying to avoid repeated send-state transitions.\n\n### Error notes\n- 404 means correspondence is missing or wrong tenant.\n- 400 means the correspondence is not send-ready.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"correspondenceId","in":"path","description":"QuickRCM AR correspondence identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."},"confirmationNumber":{"type":"string","maxLength":200,"description":"Payer, portal, or internal confirmation number captured after a call, correspondence, appeal, or submission-like workflow."}}},"example":{"queueOnly":true,"confirmationNumber":"example-confirmationnumber"}}},"description":"Use dryRun or queueOnly where supported to avoid claiming external delivery before delivery channels are enabled."},"responses":{"200":{"description":"Queued AR correspondence send.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"correspondence":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"}},"required":["id","organizationId"]}},"required":["correspondence"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"correspondence":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"AR correspondence was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/correspondence/{correspondenceId}/response":{"put":{"operationId":"recordArCorrespondenceResponse","summary":"Record AR correspondence response","description":"Records response metadata for organization-scoped AR correspondence.\n\n### When to use\nUse this when a payer, patient, agency, or internal reviewer responds to a previously generated AR correspondence item.\n\n### Before calling\nConfirm the correspondenceId and collect outcome, response notes, confirmation, dollars recovered, or next action context.\n\n### Request guidance\nUse responseNotes and outcome for staff-readable context. Keep raw payer payloads and unnecessary PHI out of notes.\n\n### Request notes\n- outcome should summarize the result.\n- dollarsRecovered should only be set when recovery is confirmed.\n\n### Response semantics\nThe response records local correspondence outcome evidence and may support downstream AR reporting.\n\n### Response notes\n- Creates local response evidence.\n- Does not itself post payments or adjudicate claims.\n\n### Errors and retries\nCheck existing response metadata after a timeout before retrying to avoid duplicate outcome records.\n\n### Error notes\n- 400 means response metadata is invalid.\n- 404 means the correspondence record is unavailable to this tenant.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"correspondenceId","in":"path","description":"QuickRCM AR correspondence identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"responseNotes":{"type":"string","minLength":1,"maxLength":10000,"description":"Notes about the response received from a payer, patient, agency, or internal reviewer."}},"required":["responseNotes"]},"example":{"responseNotes":"Example ar_correspondence_response note"}}},"description":"Use responseNotes and outcome for staff-readable context. Keep raw payer payloads and unnecessary PHI out of notes."},"responses":{"200":{"description":"Updated AR correspondence response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"correspondence":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"}},"required":["id","organizationId"]}},"required":["correspondence"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"correspondence":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"AR correspondence was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/patient-accounts/{accountId}/payment-plans":{"post":{"operationId":"createArPaymentPlan","summary":"Create patient AR payment plan","description":"Creates a local patient Accounts Receivable payment plan after account ownership and active-plan checks.\n\n### When to use\nUse this when a patient or guarantor agrees to pay an outstanding balance over scheduled installments.\n\n### Before calling\nVerify the patient account, total balance, first payment date, installment count, and autopay expectations outside this endpoint.\n\n### Request guidance\nSend payment-plan schedule metadata only. Do not send card numbers, bank accounts, or processor tokens.\n\n### Request notes\n- installmentAmount and totalInstallments define the schedule.\n- autoPayEnabled is metadata and not payment credential storage.\n\n### Response semantics\nA successful response creates local plan tracking. It does not charge a card or guarantee payment collection.\n\n### Response notes\n- Creates local plan tracking.\n- Payment processing remains separate.\n\n### Errors and retries\nDo not retry after a timeout until checking for an active plan on the account; duplicate payment plans can confuse billing workflows.\n\n### Error notes\n- 400 means invalid schedule values.\n- 409 can indicate an active plan already exists when exposed.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"accountId","in":"path","description":"QuickRCM patient accounts receivable account identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"installmentAmount":{"type":"number","exclusiveMinimum":0,"description":"Payment amount for each patient payment-plan installment. Use a decimal number and do not include card data."},"frequency":{"type":"string","enum":["WEEKLY","BI_WEEKLY","MONTHLY","QUARTERLY","ONE_TIME"],"default":"MONTHLY","description":"Payment-plan cadence such as monthly, biweekly, weekly, or another supported billing interval."},"startDate":{"type":"string","format":"date-time","description":"Start date for a payment plan, service period, or workflow schedule. Use an ISO date string."},"totalInstallments":{"type":"integer","minimum":1,"maximum":120,"description":"Total number of scheduled installments in a patient payment plan."},"autoPayEnabled":{"type":"boolean","default":false,"description":"Whether the patient payment plan is expected to use automatic payments. This flag does not store card data."},"gracePeriodDays":{"type":["integer","null"],"minimum":0,"maximum":90,"default":0,"description":"Number of days after a scheduled installment date before the plan is considered late."}},"required":["installmentAmount","startDate","totalInstallments"]},"example":{"installmentAmount":125.5,"startDate":"2026-06-08T10:15:30Z","totalInstallments":1,"frequency":"MONTHLY","autoPayEnabled":false,"gracePeriodDays":0}}},"description":"Send payment-plan schedule metadata only. Do not send card numbers, bank accounts, or processor tokens."},"responses":{"201":{"description":"Created patient AR payment plan.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"paymentPlan":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"}},"required":["id","organizationId"]}},"required":["paymentPlan"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"paymentPlan":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient account was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Patient account already has an active payment plan.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/ar-management/patient-accounts/{accountId}/financial-assistance":{"post":{"operationId":"queueArFinancialAssistance","summary":"Queue patient AR financial assistance review","description":"Queues a patient financial-assistance review using a PHI-safe local audit record without directly applying discounts.\n\n### When to use\nUse this when a patient balance should be reviewed for charity care, hardship, discount eligibility, or financial-assistance policy.\n\n### Before calling\nResolve the patient account and collect household size, income, notes, and any supporting review context according to policy.\n\n### Request guidance\nTreat income and notes as sensitive. Do not include tax documents, credentials, or raw uploaded files in this request body.\n\n### Request notes\n- annualHouseholdIncome and householdSize support review routing.\n- applicationNotes should stay concise and policy-oriented.\n\n### Response semantics\nThe response means a local review was queued. It does not approve assistance or reduce the patient balance.\n\n### Response notes\n- Queues a local review.\n- Does not apply discounts or alter balances directly.\n\n### Errors and retries\nCheck review history after timeouts before queueing another review.\n\n### Error notes\n- 400 means financial-assistance inputs are invalid.\n- 404 means accountId is unavailable to this tenant.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"accountId","in":"path","description":"QuickRCM patient accounts receivable account identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"annualHouseholdIncome":{"type":["number","null"],"minimum":0,"description":"Annual household income used for patient financial-assistance screening. Treat as sensitive financial information."},"householdSize":{"type":"integer","minimum":1,"maximum":20,"description":"Number of people in the household for financial-assistance review."},"applicationNotes":{"type":"string","maxLength":10000,"description":"Internal notes explaining a financial-assistance application or review. Do not include unnecessary PHI or payment credentials."}},"required":["annualHouseholdIncome","householdSize"]},"example":{"annualHouseholdIncome":1.25,"householdSize":1,"applicationNotes":"Example ar_financial_assistance note"}}},"description":"Treat income and notes as sensitive. Do not include tax documents, credentials, or raw uploaded files in this request body."},"responses":{"202":{"description":"Financial assistance review queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string"}},"required":["status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"status":"queued"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient account was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/patient-accounts/{accountId}/collection-stage":{"put":{"operationId":"advanceArCollectionStage","summary":"Advance patient AR collection stage","description":"Advances a patient AR account collection stage and creates a local collection task.\n\n### When to use\nUse this when an account should move through internal collection policy stages after notices, failed payments, or escalation rules.\n\n### Before calling\nVerify the account balance, policy requirements, notice history, and whether forceAdvance is allowed for the caller.\n\n### Request guidance\nUse escalationReason and notes for audit context. Do not include payment credentials or unrelated PHI.\n\n### Request notes\n- targetStatus or level describes the requested collection movement.\n- forceAdvance should be rare and policy-controlled.\n\n### Response semantics\nThe response updates local collection-stage tracking. It does not place debt with an outside agency unless a separate integration does so.\n\n### Response notes\n- Updates local collection state.\n- External agency placement is not implied.\n\n### Errors and retries\nRe-read account stage after timeouts before retrying; duplicate transitions can corrupt audit history.\n\n### Error notes\n- 400 means the transition is invalid.\n- 403 means the caller cannot perform the collection-stage action.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"accountId","in":"path","description":"QuickRCM patient accounts receivable account identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"forceAdvance":{"type":"boolean","default":false,"description":"Whether to bypass normal collection-stage transition checks. Use only for controlled administrative workflows."},"targetStatus":{"type":"string","enum":["CURRENT","PAST_DUE","PRE_COLLECT","IN_COLLECT","AGENCY","LEGAL","PAYMENT_PLAN","HARDSHIP"],"description":"New workflow status requested by a status-update action."},"notes":{"type":"string","maxLength":2000,"description":"Human-readable note for staff context. Keep it concise and avoid secrets, raw EDI, and unnecessary PHI."}}},"example":{"forceAdvance":false,"targetStatus":"CURRENT","notes":"Example ar_collection_stage note"}}},"description":"Use escalationReason and notes for audit context. Do not include payment credentials or unrelated PHI."},"responses":{"200":{"description":"Collection stage transition result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"previousStage":{"type":"string"},"newStage":{"type":"string"}},"required":["previousStage","newStage"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"previousStage":"example-previousstage","newStage":"example-newstage"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient account was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/appeals":{"post":{"operationId":"createArAppeal","summary":"Create AR appeal tracking record","description":"Creates a local AR appeal tracking record from an organization-scoped denial or recovery context.\n\n### When to use\nUse this when AR follow-up escalates into formal appeal tracking, payer dispute work, or denial recovery.\n\n### Before calling\nResolve the claim or denial context and capture reason code, deadline, appeal type, and supporting notes.\n\n### Request guidance\nUse notes and reasonCode to explain the appeal basis. Keep supporting documents in the file/artifact workflow rather than embedding them.\n\n### Request notes\n- deadline is important for payer timely-filing and appeal windows.\n- reasonCode should preserve payer or denial source code where available.\n\n### Response semantics\nA successful response creates local appeal tracking. It does not submit an appeal externally unless a separate workflow is enabled.\n\n### Response notes\n- Creates local appeal tracking.\n- External appeal submission remains separate.\n\n### Errors and retries\nCheck for an existing appeal before retrying after a timeout.\n\n### Error notes\n- 400 means appeal context is invalid.\n- 404 means referenced claim or denial context is unavailable to this tenant.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimId":{"type":"string","minLength":1,"description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."},"level":{"type":"integer","minimum":1,"maximum":5,"default":1,"description":"Collection, urgency, or stage level used by the module workflow. Valid values depend on the endpoint schema."},"deadline":{"type":"string","format":"date-time","description":"Due date or deadline for appeal, follow-up, collection, or payer action. Use ISO date strings when a date is expected."},"assignedToId":{"type":"string","minLength":1,"description":"QuickRCM user identifier for the staff member assigned to the work item. The assignee must belong to the same organization."},"notes":{"type":"string","maxLength":5000,"description":"Human-readable note for staff context. Keep it concise and avoid secrets, raw EDI, and unnecessary PHI."}},"required":["claimId"]},"example":{"claimId":"00000000-0000-4000-8000-000000000001","level":1,"deadline":"2026-06-08T10:15:30Z","assignedToId":"00000000-0000-4000-8000-000000000001","notes":"Example ar_appeal note"}}},"description":"Use notes and reasonCode to explain the appeal basis. Keep supporting documents in the file/artifact workflow rather than embedding them."},"responses":{"201":{"description":"Created AR appeal tracking record.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"}},"required":["id","organizationId"]}},"required":["appeal"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial case was not found for the claim.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/ar-management/appeals/{appealId}":{"put":{"operationId":"updateArAppeal","summary":"Update AR appeal tracking record","description":"Updates an organization-scoped AR appeal tracking record.\n\n### When to use\nUse this when appeal status, deadline, notes, recovery amount, or response context changes.\n\n### Before calling\nLoad the current appeal state and determine whether the update is administrative, payer response, recovery, or closure.\n\n### Request guidance\nUse status, responseNotes, dollarsRecovered, and confirmationNumber only when those facts are known and supportable.\n\n### Request notes\n- appealId selects the appeal record.\n- dollarsRecovered should reflect confirmed recovery only.\n\n### Response semantics\nThe response updates local appeal tracking and reporting context. It does not post cash or alter payer adjudication by itself.\n\n### Response notes\n- Returns updated local appeal tracking.\n- Payment posting and payer adjudication are separate workflows.\n\n### Errors and retries\nRe-read appeal state after a timeout to avoid duplicate notes or stale status updates.\n\n### Error notes\n- 400 means invalid appeal update data.\n- 404 means appealId is missing or wrong tenant.\n","tags":["AR Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"QuickRCM appeal tracking identifier. It must resolve to an appeal record owned by the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["DRAFT","PENDING_DOCUMENTATION","READY_FOR_SUBMISSION","SUBMITTED","RECEIVED_ACKNOWLEDGED","UNDER_REVIEW","PEER_TO_PEER_SCHEDULED","PEER_TO_PEER_COMPLETED","ADDITIONAL_INFO_REQUESTED","DECIDED_FAVORABLE","DECIDED_PARTIAL","DECIDED_UNFAVORABLE","ESCALATED_TO_NEXT_LEVEL","WITHDRAWN","EXPIRED"],"description":"Workflow status filter or target status. Valid values depend on the endpoint schema and module state machine."},"level":{"type":"integer","minimum":1,"maximum":5,"description":"Collection, urgency, or stage level used by the module workflow. Valid values depend on the endpoint schema."},"dollarsRecovered":{"type":["number","null"],"minimum":0,"description":"Recovered amount associated with an AR, appeal, or collection outcome. Preserve decimal precision."},"dueDate":{"type":"string","format":"date-time","description":"Date when the work item, appeal, correspondence, or collection task should be completed."},"assignedToId":{"type":"string","minLength":1,"description":"QuickRCM user identifier for the staff member assigned to the work item. The assignee must belong to the same organization."}}},"example":{"status":"DRAFT","level":1,"dollarsRecovered":1.25,"dueDate":"2026-06-08T10:15:30Z","assignedToId":"00000000-0000-4000-8000-000000000001"}}},"description":"Use status, responseNotes, dollarsRecovered, and confirmationNumber only when those facts are known and supportable."},"responses":{"200":{"description":"Updated AR appeal tracking record.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"}},"required":["id","organizationId"]}},"required":["appeal"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"AR appeal tracking record was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/billing/encounters":{"get":{"operationId":"listBillingEncounters","summary":"List billing encounters","description":"Lists billing encounters in the authenticated organization with bounded pagination and optional status, encounter type, external encounter ID, and patient filters.\n\n### When to use\nUse this for a hospital billing worklist, processing-status monitoring, or to locate an encounter before detail reads, review edits, or queued workflows.\n\n### Before calling\nAuthenticate with an API key that has `billing:read` or `billing:write`. Choose filters from the Billing enums and keep pagination explicit for repeatable syncing.\n\n### Request guidance\n`page` defaults to 1 and `pageSize` defaults to 25 with a maximum of 100. Optional filters are `status`, `encounterType`, `externalEncounterId`, and `patientId`; this endpoint does not accept `organizationId` as caller-controlled tenant context.\n\n### Request notes\n- `status` accepts INGESTED, CHUNKING, TIER1_PROCESSING, ROUTING, TIER2_PROCESSING, POST_PROCESSING, HUMAN_REVIEW, FINALIZED, SUBMITTED, or FAILED.\n- `encounterType` accepts INPATIENT, OUTPATIENT, EMERGENCY, or OBSERVATION.\n- `pageSize` is capped at 100.\n- Tenant scope is derived from the API key, not from request parameters.\n\n### Response semantics\nHTTP 200 returns `encounters`, `total`, `page`, `pageSize`, and `totalPages`. Each encounter summary includes identifiers, encounter dates, status, routing decision, confidence/complexity scores, page/token/cost totals, coded-entry/query/source-file counts, nullable `claimId`, and timestamps.\n\n### Response notes\n- `routingDecision` is nullable or one of FAST, SELECTIVE_DEEP, or DEEP.\n- `claimId` is nullable until a claim exists or is linked.\n- Use getBillingEncounter for coded entries, DRG/E/M summaries, and processing logs.\n\n### Errors and retries\nTreat 400 as an invalid filter or pagination value, 401/403 as API key or scope/tenant authorization failure, and 429 as a rate-limit signal. Reads can be retried with the same filters after transient failures.\n\n### Error notes\n- Treat 400 as an invalid filter or pagination value, 401/403 as API key or scope/tenant authorization failure, and 429 as a rate-limit signal. Reads can be retried with the same filters after transient failures.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query","description":"One-based COB pagination page number."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"Number of records per page, maximum 100."},{"schema":{"type":"string","enum":["INGESTED","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","POST_PROCESSING","HUMAN_REVIEW","FINALIZED","SUBMITTED","FAILED"],"description":"Current billing encounter processing status."},"required":false,"description":"Optional billing encounter processing status filter.","name":"status","in":"query"},{"schema":{"type":"string","enum":["INPATIENT","OUTPATIENT","EMERGENCY","OBSERVATION"],"description":"Hospital billing encounter type."},"required":false,"description":"Optional hospital billing encounter type filter.","name":"encounterType","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"externalEncounterId","in":"query","description":"Optional external encounter reference stored on the Billing encounter."},{"schema":{"type":"string","minLength":1},"required":false,"name":"patientId","in":"query","description":"Optional QuickRCM patient identifier filter."}],"responses":{"200":{"description":"Billing encounters for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"encounters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"externalEncounterId":{"type":["string","null"]},"patientId":{"type":"string"},"facilityId":{"type":"string"},"encounterType":{"type":"string","enum":["INPATIENT","OUTPATIENT","EMERGENCY","OBSERVATION"],"description":"Hospital billing encounter type."},"dateOfService":{"type":"string","format":"date-time"},"admitDate":{"type":["string","null"],"format":"date-time"},"dischargeDate":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["INGESTED","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","POST_PROCESSING","HUMAN_REVIEW","FINALIZED","SUBMITTED","FAILED"],"description":"Current billing encounter processing status."},"routingDecision":{"type":["string","null"],"enum":["FAST","SELECTIVE_DEEP","DEEP"],"description":"AI coding routing path selected for the encounter."},"overallConfidence":{"type":["number","null"]},"overallComplexityScore":{"type":["integer","null"]},"totalPages":{"type":"integer"},"totalTokensUsed":{"type":"integer"},"totalCostCents":{"type":"integer"},"codedEntriesCount":{"type":"integer"},"physicianQueriesCount":{"type":"integer"},"sourceFilesCount":{"type":"integer"},"claimId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","externalEncounterId","patientId","facilityId","encounterType","dateOfService","admitDate","dischargeDate","status","routingDecision","overallConfidence","overallComplexityScore","totalPages","totalTokensUsed","totalCostCents","codedEntriesCount","physicianQueriesCount","sourceFilesCount","claimId","createdAt","updatedAt"]}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["encounters","total","page","pageSize","totalPages"]}},"required":["success","data"]},"example":{"success":true,"data":{"encounters":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","externalEncounterId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","encounterType":"INPATIENT","dateOfService":"2026-06-08T10:15:30Z","admitDate":"2026-06-08T10:15:30Z","dischargeDate":"2026-06-08T10:15:30Z","status":"INGESTED","routingDecision":"FAST","overallConfidence":1.25,"overallComplexityScore":1,"totalPages":1,"totalTokensUsed":1,"totalCostCents":1,"codedEntriesCount":1,"physicianQueriesCount":1,"sourceFilesCount":1,"claimId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1,"totalPages":1}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}},"post":{"operationId":"createBillingEncounter","summary":"Create billing encounter","description":"Creates an INGESTED hospital billing encounter for the authenticated organization without running inline AI processing.\n\n### When to use\nUse this when an upstream EHR, document intake, or billing workflow needs to register an encounter before attaching files, running processing, editing codes, or finalizing.\n\n### Before calling\nResolve same-tenant `patientId` and `facilityId`. Optionally resolve appointment, payer configuration, patient insurance, attending provider, and existing file IDs.\n\n### Request guidance\nSend required `patientId`, `facilityId`, `encounterType`, and ISO 8601 `dateOfService`. `fileIds` links existing organization-owned files and is capped at 25. Optional date and reference fields must point to same-tenant QuickRCM records where supplied.\n\n### Request notes\n- `encounterType` must be INPATIENT, OUTPATIENT, EMERGENCY, or OBSERVATION.\n- `fileIds` references existing files; this is not a binary upload endpoint.\n- `appointmentId` is optional because Billing encounters can exist without appointments.\n- `externalEncounterId` should be an opaque external reference, not a raw EHR payload.\n\n### Response semantics\nHTTP 201 returns the created encounter detail with status INGESTED, count fields, nullable assignment outputs, processing logs, and any linked source-file count. The generated default 200 mutation response is less specific than the concrete creation response.\n\n### Response notes\n- New encounters are created with `status: INGESTED`.\n- `codedEntries`, `drgAssignment`, and `emLevelAssignment` may be empty or null immediately after creation.\n- Use addBillingEncounterFiles or reprocessBillingEncounter to queue later processing work where appropriate.\n\n### Errors and retries\nAfter timeout, search by `externalEncounterId` or list recent encounters before retrying to avoid duplicates. Fix 404s for referenced patients, facilities, appointments, payer configs, insurance records, providers, or files before resubmitting.\n\n### Error notes\n- After timeout, search by `externalEncounterId` or list recent encounters before retrying to avoid duplicates. Fix 404s for referenced patients, facilities, appointments, payer configs, insurance records, providers, or files before resubmitting.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"externalEncounterId":{"type":"string","minLength":1,"maxLength":255,"description":"Opaque external or EHR encounter reference stored on a Billing encounter; not a raw EHR payload."},"patientId":{"type":"string","minLength":1,"description":"Required same-tenant QuickRCM patient identifier."},"facilityId":{"type":"string","minLength":1,"description":"Required same-tenant QuickRCM facility identifier."},"encounterType":{"type":"string","enum":["INPATIENT","OUTPATIENT","EMERGENCY","OBSERVATION"],"description":"Required hospital billing encounter type."},"dateOfService":{"type":"string","format":"date-time","description":"Required ISO 8601 service date-time."},"admitDate":{"type":["string","null"],"format":"date-time","description":"Optional nullable ISO 8601 admission date-time."},"dischargeDate":{"type":["string","null"],"format":"date-time","description":"Optional nullable ISO 8601 discharge date-time."},"appointmentId":{"type":"string","minLength":1,"description":"Nullable QuickRCM appointment identifier linked to the local claim when an appointment exists."},"payerConfigId":{"type":"string","minLength":1,"description":"QuickRCM payer configuration identifier used for routing, payer metadata, and organization-specific payer settings."},"patientInsuranceId":{"type":"string","minLength":1,"description":"QuickRCM patient insurance record identifier associated with the patient and claim."},"attendingProviderId":{"type":"string","minLength":1},"fileIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":25,"default":[],"description":"Existing same-tenant QuickRCM file IDs to connect to the new encounter, maximum 25."}},"required":["patientId","facilityId","encounterType","dateOfService"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","encounterType":"INPATIENT","dateOfService":"2026-06-08T10:15:30Z","externalEncounterId":"00000000-0000-4000-8000-000000000001","admitDate":"2026-06-08T10:15:30Z","dischargeDate":"2026-06-08T10:15:30Z","appointmentId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","attendingProviderId":"00000000-0000-4000-8000-000000000001","fileIds":[]}}},"description":"Send required `patientId`, `facilityId`, `encounterType`, and ISO 8601 `dateOfService`. `fileIds` links existing organization-owned files and is capped at 25. Optional date and reference fields must point to same-tenant QuickRCM records where supplied."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Billing encounter created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"externalEncounterId":{"type":["string","null"]},"patientId":{"type":"string"},"facilityId":{"type":"string"},"encounterType":{"type":"string","enum":["INPATIENT","OUTPATIENT","EMERGENCY","OBSERVATION"],"description":"Hospital billing encounter type."},"dateOfService":{"type":"string","format":"date-time"},"admitDate":{"type":["string","null"],"format":"date-time"},"dischargeDate":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["INGESTED","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","POST_PROCESSING","HUMAN_REVIEW","FINALIZED","SUBMITTED","FAILED"],"description":"Current billing encounter processing status."},"routingDecision":{"type":["string","null"],"enum":["FAST","SELECTIVE_DEEP","DEEP"],"description":"AI coding routing path selected for the encounter."},"overallConfidence":{"type":["number","null"]},"overallComplexityScore":{"type":["integer","null"]},"totalPages":{"type":"integer"},"totalTokensUsed":{"type":"integer"},"totalCostCents":{"type":"integer"},"codedEntriesCount":{"type":"integer"},"physicianQueriesCount":{"type":"integer"},"sourceFilesCount":{"type":"integer"},"claimId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"codedEntries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"codeType":{"type":"string","enum":["ICD10_CM","ICD10_PCS","CPT","HCPCS","DRG"]},"code":{"type":"string"},"description":{"type":"string"},"isPrincipal":{"type":"boolean"},"sequenceNumber":{"type":["integer","null"]},"modifiers":{"type":"array","items":{"type":"string"}},"confidence":{"type":"number"},"assignedBy":{"type":"string","enum":["TIER1","TIER2","HUMAN","RULE_ENGINE"]},"medicalNecessityStatus":{"type":"string","enum":["VERIFIED","AT_RISK","FAILED","PENDING"]},"ncciStatus":{"type":"string","enum":["PASSED","BUNDLED","MODIFIER_REQUIRED","MUTUALLY_EXCLUSIVE"]}},"required":["id","codeType","code","description","isPrincipal","sequenceNumber","modifiers","confidence","assignedBy","medicalNecessityStatus","ncciStatus"]}},"drgAssignment":{"type":["object","null"],"properties":{"drgCode":{"type":"string"},"description":{"type":"string"},"mdc":{"type":"string"},"weight":{"type":"number"},"confidence":{"type":"number"}},"required":["drgCode","description","mdc","weight","confidence"]},"emLevelAssignment":{"type":["object","null"],"properties":{"emCode":{"type":"string"},"mdmComplexity":{"type":"string"},"confidence":{"type":"number"},"assignedBy":{"type":"string","enum":["TIER1","TIER2","HUMAN","RULE_ENGINE"]},"humanOverride":{"type":"boolean"}},"required":["emCode","mdmComplexity","confidence","assignedBy","humanOverride"]},"processingLogs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"step":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","step","status","createdAt"]}}},"required":["id","organizationId","externalEncounterId","patientId","facilityId","encounterType","dateOfService","admitDate","dischargeDate","status","routingDecision","overallConfidence","overallComplexityScore","totalPages","totalTokensUsed","totalCostCents","codedEntriesCount","physicianQueriesCount","sourceFilesCount","claimId","createdAt","updatedAt","codedEntries","drgAssignment","emLevelAssignment","processingLogs"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","externalEncounterId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","encounterType":"INPATIENT","dateOfService":"2026-06-08T10:15:30Z","admitDate":"2026-06-08T10:15:30Z","dischargeDate":"2026-06-08T10:15:30Z","status":"INGESTED","routingDecision":"FAST","overallConfidence":1.25,"overallComplexityScore":1,"totalPages":1,"totalTokensUsed":1,"totalCostCents":1,"codedEntriesCount":1,"physicianQueriesCount":1,"sourceFilesCount":1,"claimId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","codedEntries":[{"id":"00000000-0000-4000-8000-000000000001","codeType":"ICD10_CM","code":"ERROR","description":"Example billing_encounter note","isPrincipal":true,"sequenceNumber":1,"modifiers":["example-modifiers"],"confidence":1.25,"assignedBy":"TIER1","medicalNecessityStatus":"VERIFIED","ncciStatus":"PASSED"}],"drgAssignment":{"drgCode":"example-drgcode","description":"Example billing_encounter note","mdc":"example-mdc","weight":1.25,"confidence":1.25},"emLevelAssignment":{"emCode":"example-emcode","mdmComplexity":"example-mdmcomplexity","confidence":1.25,"assignedBy":"TIER1","humanOverride":true},"processingLogs":[{"id":"00000000-0000-4000-8000-000000000001","step":"example-step","status":"active","createdAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}":{"get":{"operationId":"getBillingEncounter","summary":"Get billing encounter","description":"Returns detailed billing status and coding outputs for one encounter in the authenticated organization.\n\n### When to use\nUse this to poll processing progress, inspect generated or human-reviewed codes, confirm DRG or E/M summaries, or verify the effect of a write or queued workflow.\n\n### Before calling\nObtain `encounterId` from listBillingEncounters, createBillingEncounter, an import workflow, or another trusted QuickRCM handoff.\n\n### Request guidance\nPass `encounterId` in the path. No request body is accepted.\n\n### Request notes\n- `encounterId` is path-only.\n- Use this endpoint after local writes and queue acknowledgements to confirm persisted state.\n- Do not infer claim submission completion from encounter finalization alone.\n\n### Response semantics\nHTTP 200 returns the encounter summary fields plus `codedEntries`, nullable `drgAssignment`, nullable `emLevelAssignment`, and up to 50 recent `processingLogs`.\n\n### Response notes\n- `codedEntries` include code type, code, description, principal marker, sequence number, modifiers, confidence, assignment source, medical necessity status, and NCCI status.\n- `drgAssignment` and `emLevelAssignment` are nullable.\n- `processingLogs` include step, status, and timestamp summaries without raw source-document content.\n\n### Errors and retries\nA 404 can mean the encounter does not exist or is outside the API key organization. When polling, use backoff and stop on terminal statuses such as FINALIZED, SUBMITTED, or FAILED according to the workflow you are observing.\n\n### Error notes\n- A 404 can mean the encounter does not exist or is outside the API key organization. When polling, use backoff and stop on terminal statuses such as FINALIZED, SUBMITTED, or FAILED according to the workflow you are observing.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"QuickRCM Billing encounter identifier."}],"responses":{"200":{"description":"Billing encounter detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"externalEncounterId":{"type":["string","null"]},"patientId":{"type":"string"},"facilityId":{"type":"string"},"encounterType":{"type":"string","enum":["INPATIENT","OUTPATIENT","EMERGENCY","OBSERVATION"],"description":"Hospital billing encounter type."},"dateOfService":{"type":"string","format":"date-time"},"admitDate":{"type":["string","null"],"format":"date-time"},"dischargeDate":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["INGESTED","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","POST_PROCESSING","HUMAN_REVIEW","FINALIZED","SUBMITTED","FAILED"],"description":"Current billing encounter processing status."},"routingDecision":{"type":["string","null"],"enum":["FAST","SELECTIVE_DEEP","DEEP"],"description":"AI coding routing path selected for the encounter."},"overallConfidence":{"type":["number","null"]},"overallComplexityScore":{"type":["integer","null"]},"totalPages":{"type":"integer"},"totalTokensUsed":{"type":"integer"},"totalCostCents":{"type":"integer"},"codedEntriesCount":{"type":"integer"},"physicianQueriesCount":{"type":"integer"},"sourceFilesCount":{"type":"integer"},"claimId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"codedEntries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"codeType":{"type":"string","enum":["ICD10_CM","ICD10_PCS","CPT","HCPCS","DRG"]},"code":{"type":"string"},"description":{"type":"string"},"isPrincipal":{"type":"boolean"},"sequenceNumber":{"type":["integer","null"]},"modifiers":{"type":"array","items":{"type":"string"}},"confidence":{"type":"number"},"assignedBy":{"type":"string","enum":["TIER1","TIER2","HUMAN","RULE_ENGINE"]},"medicalNecessityStatus":{"type":"string","enum":["VERIFIED","AT_RISK","FAILED","PENDING"]},"ncciStatus":{"type":"string","enum":["PASSED","BUNDLED","MODIFIER_REQUIRED","MUTUALLY_EXCLUSIVE"]}},"required":["id","codeType","code","description","isPrincipal","sequenceNumber","modifiers","confidence","assignedBy","medicalNecessityStatus","ncciStatus"]}},"drgAssignment":{"type":["object","null"],"properties":{"drgCode":{"type":"string"},"description":{"type":"string"},"mdc":{"type":"string"},"weight":{"type":"number"},"confidence":{"type":"number"}},"required":["drgCode","description","mdc","weight","confidence"]},"emLevelAssignment":{"type":["object","null"],"properties":{"emCode":{"type":"string"},"mdmComplexity":{"type":"string"},"confidence":{"type":"number"},"assignedBy":{"type":"string","enum":["TIER1","TIER2","HUMAN","RULE_ENGINE"]},"humanOverride":{"type":"boolean"}},"required":["emCode","mdmComplexity","confidence","assignedBy","humanOverride"]},"processingLogs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"step":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","step","status","createdAt"]}}},"required":["id","organizationId","externalEncounterId","patientId","facilityId","encounterType","dateOfService","admitDate","dischargeDate","status","routingDecision","overallConfidence","overallComplexityScore","totalPages","totalTokensUsed","totalCostCents","codedEntriesCount","physicianQueriesCount","sourceFilesCount","claimId","createdAt","updatedAt","codedEntries","drgAssignment","emLevelAssignment","processingLogs"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","externalEncounterId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","encounterType":"INPATIENT","dateOfService":"2026-06-08T10:15:30Z","admitDate":"2026-06-08T10:15:30Z","dischargeDate":"2026-06-08T10:15:30Z","status":"INGESTED","routingDecision":"FAST","overallConfidence":1.25,"overallComplexityScore":1,"totalPages":1,"totalTokensUsed":1,"totalCostCents":1,"codedEntriesCount":1,"physicianQueriesCount":1,"sourceFilesCount":1,"claimId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","codedEntries":[{"id":"00000000-0000-4000-8000-000000000001","codeType":"ICD10_CM","code":"ERROR","description":"Example billing_encounter note","isPrincipal":true,"sequenceNumber":1,"modifiers":["example-modifiers"],"confidence":1.25,"assignedBy":"TIER1","medicalNecessityStatus":"VERIFIED","ncciStatus":"PASSED"}],"drgAssignment":{"drgCode":"example-drgcode","description":"Example billing_encounter note","mdc":"example-mdc","weight":1.25,"confidence":1.25},"emLevelAssignment":{"emCode":"example-emcode","mdmComplexity":"example-mdmcomplexity","confidence":1.25,"assignedBy":"TIER1","humanOverride":true},"processingLogs":[{"id":"00000000-0000-4000-8000-000000000001","step":"example-step","status":"active","createdAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Billing encounter not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}},"put":{"operationId":"updateBillingEncounter","summary":"Update billing encounter","description":"Updates safe claim-form and encounter-reference fields on an editable Billing encounter.\n\n### When to use\nUse this during human billing review to correct encounter dates, encounter type, provider references, payer references, patient-insurance reference, and institutional claim-form fields before submission.\n\n### Before calling\nRead the encounter first, confirm it is not submitted, and resolve any provider, payer configuration, or patient insurance references in the same organization.\n\n### Request guidance\nSend only fields that should change. At least one update field is required. `encounterType` uses the Billing encounter type enum, date fields are ISO 8601 date-times, and admit type/source, discharge status, and bill type strings are capped at 10 characters.\n\n### Request notes\n- The handler excludes SUBMITTED encounters from update.\n- Nullable reference fields can be set to null where the schema allows.\n- Referenced providers, payer configs, and insurance records are validated inside the API key organization.\n\n### Response semantics\nHTTP 200 returns `success: true` with the updated encounter detail from the handler. The generated OpenAPI schema for this mutation is generic, so final docs should document the concrete runtime fields and recommend getBillingEncounter for read-after-write verification.\n\n### Response notes\n- Runtime response data is the mapped encounter detail, not an empty acknowledgement.\n- Generated OpenAPI currently represents this as a generic mutation response.\n- Follow-up getBillingEncounter is still useful when downstream workflows may alter derived outputs.\n\n### Errors and retries\nA 400 can mean no fields were supplied or a field failed validation. A 404 can mean the encounter is missing, outside the tenant, submitted, or a referenced resource was not found. After timeout, call getBillingEncounter before retrying.\n\n### Error notes\n- A 400 can mean no fields were supplied or a field failed validation. A 404 can mean the encounter is missing, outside the tenant, submitted, or a referenced resource was not found. After timeout, call getBillingEncounter before retrying.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"externalEncounterId":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Nullable external encounter reference, maximum 255 characters."},"encounterType":{"type":"string","enum":["INPATIENT","OUTPATIENT","EMERGENCY","OBSERVATION"],"description":"Hospital Billing encounter type: INPATIENT, OUTPATIENT, EMERGENCY, or OBSERVATION."},"dateOfService":{"type":"string","format":"date-time","description":"Service date for a queued appointment eligibility check. Defaults to the appointment start date when omitted."},"admitDate":{"type":["string","null"],"format":"date-time","description":"Nullable ISO 8601 admission date-time on a Billing encounter."},"dischargeDate":{"type":["string","null"],"format":"date-time","description":"Nullable ISO 8601 discharge date-time on a Billing encounter."},"attendingProviderId":{"type":["string","null"],"minLength":1,"description":"Nullable same-tenant provider identifier."},"operatingProviderId":{"type":["string","null"],"minLength":1,"description":"Nullable same-tenant provider identifier."},"referringProviderId":{"type":["string","null"],"minLength":1,"description":"Nullable same-tenant provider identifier."},"payerConfigId":{"type":["string","null"],"minLength":1,"description":"Nullable same-tenant payer configuration identifier."},"patientInsuranceId":{"type":["string","null"],"minLength":1,"description":"Nullable insurance identifier for the encounter patient."},"admitType":{"type":["string","null"],"maxLength":10,"description":"Nullable institutional billing admit type code, maximum 10 characters in update requests."},"admitSource":{"type":["string","null"],"maxLength":10,"description":"Nullable institutional billing admit source code, maximum 10 characters in update requests."},"dischargeStatus":{"type":["string","null"],"maxLength":10,"description":"Nullable institutional billing discharge status code, maximum 10 characters."},"billType":{"type":["string","null"],"maxLength":10,"description":"Nullable institutional bill type code, maximum 10 characters."}}},"example":{"externalEncounterId":"00000000-0000-4000-8000-000000000001","encounterType":"INPATIENT","dateOfService":"2026-06-08T10:15:30Z","admitDate":"2026-06-08T10:15:30Z","dischargeDate":"2026-06-08T10:15:30Z","attendingProviderId":"00000000-0000-4000-8000-000000000001","operatingProviderId":"00000000-0000-4000-8000-000000000001","referringProviderId":"00000000-0000-4000-8000-000000000001"}}},"description":"Send only fields that should change. At least one update field is required. `encounterType` uses the Billing encounter type enum, date fields are ISO 8601 date-times, and admit type/source, discharge status, and bill type strings are capped at 10 characters."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}/reprocess":{"post":{"operationId":"reprocessBillingEncounter","summary":"Queue billing encounter reprocess","description":"Queues Billing encounter reprocessing for an editable, organization-scoped encounter.\n\n### When to use\nUse this after source files, code changes, POA updates, or physician query responses mean the Billing pipeline should revisit encounter outputs.\n\n### Before calling\nConfirm the encounter belongs to the tenant and is not FINALIZED or SUBMITTED. Decide whether to provide a short reason and idempotency key for auditability and retry safety.\n\n### Request guidance\nSend `queueOnly: true`. Optional `idempotencyKey` is capped at 255 characters and optional `reason` is capped at 500 characters.\n\n### Request notes\n- `queueOnly` is a required literal true.\n- `reason` should be brief and should not include raw clinical notes or transcripts.\n- The handler checks status not in SUBMITTED or FINALIZED before queueing.\n\n### Response semantics\nHTTP 202 returns `success: true` and `data` with `queued: true`, `operation: REPROCESS_BILLING_ENCOUNTER`, and nullable `queueJobId`. This is a queue acknowledgement, not completed processing.\n\n### Response notes\n- `queueJobId` can be null if the queue adapter does not return an ID.\n- Use getBillingEncounter to observe later processing state.\n\n### Errors and retries\nReuse the same idempotency key when retrying the same request after a transport failure. Poll getBillingEncounter rather than repeatedly queueing reprocessing.\n\n### Error notes\n- Reuse the same idempotency key when retrying the same request after a transport failure. Poll getBillingEncounter rather than repeatedly queueing reprocessing.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"description":"Required public API safety control; must be true."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":255,"description":"Optional caller retry key, 1 to 255 characters."},"reason":{"type":"string","maxLength":500,"description":"Optional short reprocessing reason, maximum 500 characters."}},"required":["queueOnly"]},"example":{"queueOnly":true,"idempotencyKey":"example-idempotencykey","reason":"example-reason"}}},"description":"Send `queueOnly: true`. Optional `idempotencyKey` is capped at 255 characters and optional `reason` is capped at 500 characters."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Billing reprocess workflow queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean","enum":[true]},"operation":{"type":"string"},"queueJobId":{"type":["string","null"]}},"required":["queued","operation","queueJobId"]}},"required":["success","data"]},"example":{"success":true,"data":{"queued":true,"operation":"example-operation","queueJobId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}/files":{"post":{"operationId":"addBillingEncounterFiles","summary":"Add billing encounter files","description":"Links existing organization-owned files to a Billing encounter and queues file processing.\n\n### When to use\nUse this when additional chart documents or source files already exist as QuickRCM File records and should be processed for a Billing encounter.\n\n### Before calling\nCreate or upload file records through the appropriate file workflow first, then confirm the encounter and file IDs belong to the same organization.\n\n### Request guidance\nSend `queueOnly: true` and `fileIds` with 1 to 25 existing file IDs. Include optional `idempotencyKey` for safe retry. Do not include file bytes, signed URLs, storage keys, or raw document text.\n\n### Request notes\n- `fileIds` must contain between 1 and 25 IDs.\n- Duplicate file IDs are de-duplicated during ownership validation.\n- This is not a file upload endpoint.\n\n### Response semantics\nHTTP 202 returns queue metadata with `operation: PROCESS_BILLING_ENCOUNTER_FILES` and nullable `queueJobId`. It confirms linking and queued processing, not completed coding.\n\n### Response notes\n- Queue acknowledgement uses HTTP 202.\n- Follow getBillingEncounter for later source-file counts and processing status.\n\n### Errors and retries\nAfter timeout, read the encounter/source-file count before retrying. 404 means the encounter or one or more files were not found in the authenticated organization.\n\n### Error notes\n- After timeout, read the encounter/source-file count before retrying. 404 means the encounter or one or more files were not found in the authenticated organization.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"description":"Required literal true for public queued processing."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":255,"description":"Optional caller retry key, 1 to 255 characters."},"fileIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":25,"description":"Existing same-tenant QuickRCM file IDs to associate with the encounter."}},"required":["queueOnly","fileIds"]},"example":{"queueOnly":true,"fileIds":["example-fileids"],"idempotencyKey":"example-idempotencykey"}}},"description":"Send `queueOnly: true` and `fileIds` with 1 to 25 existing file IDs. Include optional `idempotencyKey` for safe retry. Do not include file bytes, signed URLs, storage keys, or raw document text."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Additional file processing workflow queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean","enum":[true]},"operation":{"type":"string"},"queueJobId":{"type":["string","null"]}},"required":["queued","operation","queueJobId"]}},"required":["success","data"]},"example":{"success":true,"data":{"queued":true,"operation":"example-operation","queueJobId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}/poa":{"put":{"operationId":"updateBillingEncounterPoa","summary":"Update billing encounter POA indicators","description":"Updates Present On Admission indicator data for a Billing encounter.\n\n### When to use\nUse this during inpatient or observation billing review when diagnosis-level POA information needs to be recorded before finalization or downstream validation.\n\n### Before calling\nRead the encounter and current diagnosis codes. Prepare a POA map using the local integration convention for keys.\n\n### Request guidance\nSend `poaIndicators` as an object whose values are one of `Y`, `N`, `U`, `W`, or `1`. The current schema does not document the map-key convention, so public examples should avoid asserting one.\n\n### Request notes\n- `poaIndicators` is required.\n- Each value must be Y, N, U, W, or 1.\n- The POA map key format is not specified in the OpenAPI schema or handler.\n\n### Response semantics\nHTTP 200 returns `success: true` with `data.encounterId` and the submitted `poaIndicators` map. This corrects the earlier generic-acknowledgement wording.\n\n### Response notes\n- Runtime response includes `encounterId` and `poaIndicators`.\n- Generated OpenAPI still uses the generic mutation schema.\n\n### Errors and retries\nA 400 means invalid POA shape or enum values. A 404 means the encounter is missing or outside the tenant. After timeout, re-read relevant encounter state before retrying.\n\n### Error notes\n- A 400 means invalid POA shape or enum values. A 404 means the encounter is missing or outside the tenant. After timeout, re-read relevant encounter state before retrying.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"poaIndicators":{"type":"object","additionalProperties":{"type":"string","enum":["Y","N","U","W","1"]},"description":"Required POA indicator map; values must be Y, N, U, W, or 1. Key convention remains product-defined/undocumented."}},"required":["poaIndicators"]},"example":{"poaIndicators":{}}}},"description":"Send `poaIndicators` as an object whose values are one of `Y`, `N`, `U`, `W`, or `1`. The current schema does not document the map-key convention, so public examples should avoid asserting one."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}/finalize":{"post":{"operationId":"finalizeBillingEncounter","summary":"Finalize billing encounter","description":"Moves a HUMAN_REVIEW Billing encounter to FINALIZED and optionally queues claim generation.\n\n### When to use\nUse this after human billing review is complete and the encounter is ready to lock for downstream claim preparation.\n\n### Before calling\nConfirm the encounter is in HUMAN_REVIEW and all code, POA, physician query, payer, provider, and institutional claim-form fields are ready.\n\n### Request guidance\n`generateClaim` defaults to false. When `generateClaim` is true, the handler queues `GENERATE_BILLING_CLAIM`; optional `idempotencyKey` is used in that queued payload. `queueOnly` is optional in the schema and not required for finalization.\n\n### Request notes\n- `generateClaim` defaults to false.\n- `idempotencyKey` is relevant when claim generation is queued.\n- Finalization is local state change; claim generation is a separate queued workflow.\n\n### Response semantics\nHTTP 200 returns the updated encounter detail with status FINALIZED plus `queuedClaimJobId`, which is null when `generateClaim` is false or when the queue adapter returns no ID. Claim generation is asynchronous when requested.\n\n### Response notes\n- Runtime response includes full encounter detail plus `queuedClaimJobId`.\n- `queuedClaimJobId` is nullable.\n- Do not document this as only a generic success body.\n\n### Errors and retries\n404 can mean the encounter is missing, wrong-tenant, or not in HUMAN_REVIEW. After timeout, read the encounter before retrying finalization to avoid duplicate claim-generation queue requests.\n\n### Error notes\n- 404 can mean the encounter is missing, wrong-tenant, or not in HUMAN_REVIEW. After timeout, read the encounter before retrying finalization to avoid duplicate claim-generation queue requests.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"generateClaim":{"type":"boolean","default":false,"description":"Boolean flag that queues claim generation after finalization when true."},"queueOnly":{"type":"boolean","enum":[true],"description":"Optional literal true in the schema; finalization itself is performed synchronously by the handler."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":255,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."}}},"example":{"generateClaim":false,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`generateClaim` defaults to false. When `generateClaim` is true, the handler queues `GENERATE_BILLING_CLAIM`; optional `idempotencyKey` is used in that queued payload. `queueOnly` is optional in the schema and not required for finalization."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}/unfinalize":{"post":{"operationId":"unfinalizeBillingEncounter","summary":"Unfinalize billing encounter","description":"Reopens a FINALIZED Billing encounter by moving it back to HUMAN_REVIEW.\n\n### When to use\nUse this when a finalized encounter needs additional review before submission or claim generation proceeds.\n\n### Before calling\nConfirm the encounter is FINALIZED and has not moved into submitted downstream state.\n\n### Request guidance\nSend an empty JSON body or omit fields according to the client. No request fields are defined.\n\n### Request notes\n- No body fields are defined.\n- Only FINALIZED encounters match the handler lookup.\n\n### Response semantics\nHTTP 200 returns the updated encounter detail with status HUMAN_REVIEW. The generated mutation schema is generic, but the handler returns mapped encounter detail.\n\n### Response notes\n- Runtime response includes updated encounter detail.\n- Follow with getBillingEncounter if later workflows may also be changing the record.\n\n### Errors and retries\n404 can mean missing, wrong-tenant, or not currently FINALIZED. After timeout, read the encounter before retrying.\n\n### Error notes\n- 404 can mean missing, wrong-tenant, or not currently FINALIZED. After timeout, read the encounter before retrying.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Path identifier for the FINALIZED Billing encounter to reopen."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"Send an empty JSON body or omit fields according to the client. No request fields are defined."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/bulk-finalize":{"post":{"operationId":"bulkFinalizeBillingEncounters","summary":"Queue bulk billing encounter finalization","description":"Queues bulk finalization for multiple HUMAN_REVIEW Billing encounters in the authenticated organization.\n\n### When to use\nUse this when an external review workflow has selected a batch of tenant encounters for finalization and optional claim generation.\n\n### Before calling\nConfirm every encounter ID belongs to the tenant and is in HUMAN_REVIEW. Decide whether queued claim generation should run for the batch.\n\n### Request guidance\nSend `queueOnly: true`, `encounterIds` with 1 to 100 IDs, optional `generateClaims` defaulting to false, and optional `idempotencyKey`.\n\n### Request notes\n- `queueOnly` is required and must be true.\n- `encounterIds` supports 1 to 100 IDs.\n- `generateClaims` defaults to false.\n\n### Response semantics\nHTTP 202 returns `queued: true`, `operation: BULK_FINALIZE_BILLING_ENCOUNTERS`, and nullable `queueJobId`. It does not mean each encounter has already been finalized.\n\n### Response notes\n- Queue acknowledgement uses HTTP 202.\n- Read individual encounters later for actual status.\n\n### Errors and retries\nIf any requested encounter is missing, wrong-tenant, or not in HUMAN_REVIEW, the handler returns 404. Reuse the same idempotency key when retrying the same batch after transport failure.\n\n### Error notes\n- If any requested encounter is missing, wrong-tenant, or not in HUMAN_REVIEW, the handler returns 404. Reuse the same idempotency key when retrying the same batch after transport failure.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":255,"description":"Optional caller retry key, 1 to 255 characters."},"encounterIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Array of Billing encounter IDs to finalize, 1 to 100."},"generateClaims":{"type":"boolean","default":false,"description":"Whether the queued bulk workflow should also generate claims."}},"required":["queueOnly","encounterIds"]},"example":{"queueOnly":true,"encounterIds":["example-encounterids"],"idempotencyKey":"example-idempotencykey","generateClaims":false}}},"description":"Send `queueOnly: true`, `encounterIds` with 1 to 100 IDs, optional `generateClaims` defaulting to false, and optional `idempotencyKey`."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Bulk finalization workflow queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean","enum":[true]},"operation":{"type":"string"},"queueJobId":{"type":["string","null"]}},"required":["queued","operation","queueJobId"]}},"required":["success","data"]},"example":{"success":true,"data":{"queued":true,"operation":"example-operation","queueJobId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/import":{"post":{"operationId":"importBillingBatch","summary":"Queue billing batch import","description":"Queues a Billing encounter batch import for the authenticated organization.\n\n### When to use\nUse this when an external system has a bounded set of encounter rows to hand off to QuickRCM for asynchronous import.\n\n### Before calling\nPrepare a synthetic-safe filename and rows with patient MRN references, facility IDs, service dates, and encounter types. Avoid embedding raw files or EHR payloads in this JSON request.\n\n### Request guidance\nSend `queueOnly: true`, `filename` up to 255 characters, and `rows` with 1 to 500 row objects. Each row requires `patientMrn`, `facilityId`, `dateOfService`, and `encounterType`; `admitDate` and `dischargeDate` are optional strings.\n\n### Request notes\n- `rows` minimum is 1 and maximum is 500.\n- `encounterType` uses the Billing encounter type enum.\n- `dateOfService`, `admitDate`, and `dischargeDate` are strings in the import row schema.\n\n### Response semantics\nHTTP 202 returns `queued: true`, `operation: IMPORT_BILLING_BATCH`, and nullable `queueJobId`. The handler does not create BillingEncounter rows inline.\n\n### Response notes\n- Queue acknowledgement uses HTTP 202.\n- `queueJobId` is nullable.\n- Imported encounter creation happens asynchronously.\n\n### Errors and retries\nFix validation errors for row count, missing required fields, and enum values. Reuse `idempotencyKey` for the same import retry and check downstream import results rather than resubmitting blindly.\n\n### Error notes\n- Fix validation errors for row count, missing required fields, and enum values. Reuse `idempotencyKey` for the same import retry and check downstream import results rather than resubmitting blindly.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":255,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."},"filename":{"type":"string","minLength":1,"maxLength":255,"description":"Caller-provided import filename label, maximum 255 characters."},"rows":{"type":"array","items":{"type":"object","properties":{"patientMrn":{"type":"string","minLength":1,"description":"Patient MRN reference used by import processing; do not include broader patient records."},"facilityId":{"type":"string","minLength":1,"description":"QuickRCM facility identifier supplied per row."},"dateOfService":{"type":"string","minLength":1,"description":"Service date for a queued appointment eligibility check. Defaults to the appointment start date when omitted."},"encounterType":{"type":"string","enum":["INPATIENT","OUTPATIENT","EMERGENCY","OBSERVATION"],"description":"Hospital Billing encounter type: INPATIENT, OUTPATIENT, EMERGENCY, or OBSERVATION."},"admitDate":{"type":"string","minLength":1,"description":"Nullable ISO 8601 admission date-time on a Billing encounter."},"dischargeDate":{"type":"string","minLength":1,"description":"Nullable ISO 8601 discharge date-time on a Billing encounter."}},"required":["patientMrn","facilityId","dateOfService","encounterType"]},"minItems":1,"maxItems":500,"description":"Batch import rows, minimum 1 and maximum 500."}},"required":["queueOnly","filename","rows"]},"example":{"queueOnly":true,"filename":"Example import_billing_batch","rows":[{"patientMrn":"example-patientmrn","facilityId":"00000000-0000-4000-8000-000000000001","dateOfService":"2026-06-08","encounterType":"INPATIENT","admitDate":"2026-06-08","dischargeDate":"2026-06-08"}],"idempotencyKey":"example-idempotencykey"}}},"description":"Send `queueOnly: true`, `filename` up to 255 characters, and `rows` with 1 to 500 row objects. Each row requires `patientMrn`, `facilityId`, `dateOfService`, and `encounterType`; `admitDate` and `dischargeDate` are optional strings."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Billing batch import queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean","enum":[true]},"operation":{"type":"string"},"queueJobId":{"type":["string","null"]}},"required":["queued","operation","queueJobId"]}},"required":["success","data"]},"example":{"success":true,"data":{"queued":true,"operation":"example-operation","queueJobId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}/codes":{"post":{"operationId":"addBillingEncounterCode","summary":"Add billing encounter code","description":"Adds a human-reviewed code to an editable Billing encounter.\n\n### When to use\nUse this during coder review when a diagnosis, procedure, CPT/HCPCS, or DRG code needs to be added manually before finalization.\n\n### Before calling\nConfirm the encounter belongs to the tenant and is not FINALIZED or SUBMITTED.\n\n### Request guidance\nSend required `codeType`, `code`, and `description`. Optional modifiers are capped at 8 entries and 8 characters each; diagnosis pointers are capped at 12 positive integers; sequence number and units must be positive integers when supplied.\n\n### Request notes\n- `codeType` accepts ICD10_CM, ICD10_PCS, CPT, HCPCS, or DRG.\n- `description` is required and capped at 1000 characters.\n- `notes` maps to human notes and is capped at 1000 characters.\n- The handler sets confidence to 1, assignedBy to HUMAN, medicalNecessityStatus to PENDING, and ncciStatus to PASSED.\n\n### Response semantics\nHTTP 201 returns `success: true` with `data.codedEntryId`. The created entry is marked HUMAN-assigned/human-reviewed by the handler; read the encounter to retrieve the full code list.\n\n### Response notes\n- Runtime response is a stable created-code ID object.\n- Use getBillingEncounter for the serialized code entry after creation.\n\n### Errors and retries\n400 can mean invalid field shape or attempting to add a code to a FINALIZED or SUBMITTED encounter. After timeout, read the encounter codes before retrying to avoid duplicate human codes.\n\n### Error notes\n- 400 can mean invalid field shape or attempting to add a code to a FINALIZED or SUBMITTED encounter. After timeout, read the encounter codes before retrying to avoid duplicate human codes.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"codeType":{"type":"string","enum":["ICD10_CM","ICD10_PCS","CPT","HCPCS","DRG"],"description":"Coding system/type for the new code."},"code":{"type":"string","minLength":1,"maxLength":32,"description":"Code value, maximum 32 characters."},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Human-readable code description, maximum 1000 characters."},"modifiers":{"type":"array","items":{"type":"string","minLength":1,"maxLength":8},"maxItems":8,"default":[],"description":"Array of procedure modifiers on a claim line."},"isPrincipal":{"type":"boolean","default":false,"description":"Whether the code should be marked principal."},"sequenceNumber":{"type":"integer","exclusiveMinimum":0},"revenueCode":{"type":"string","maxLength":10,"description":"Nullable institutional revenue code on a claim line."},"units":{"type":"integer","exclusiveMinimum":0},"diagnosisPointers":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"maxItems":12},"poaIndicator":{"type":"string","enum":["Y","N","U","W","1"],"description":"Optional POA indicator value: Y, N, U, W, or 1."},"notes":{"type":"string","maxLength":1000,"description":"Human-readable note for staff context. Keep it concise and avoid secrets, raw EDI, and unnecessary PHI."}},"required":["codeType","code","description"]},"example":{"codeType":"ICD10_CM","code":"ERROR","description":"Example add_billing_encounter_code note","modifiers":[],"isPrincipal":false,"sequenceNumber":1,"revenueCode":"example-revenuecode","units":1,"diagnosisPointers":[1],"poaIndicator":"Y","notes":"Example add_billing_encounter_code note"}}},"description":"Send required `codeType`, `code`, and `description`. Optional modifiers are capped at 8 entries and 8 characters each; diagnosis pointers are capped at 12 positive integers; sequence number and units must be positive integers when supplied."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Billing encounter code created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}/codes/{codedEntryId}":{"put":{"operationId":"updateBillingEncounterCode","summary":"Update billing encounter code","description":"Updates an existing code on an editable Billing encounter and marks it human-reviewed.\n\n### When to use\nUse this during coder review to correct code value, description, modifiers, principal flag, sequence, revenue code, units, diagnosis pointers, POA indicator, or human notes.\n\n### Before calling\nConfirm the coded entry belongs to the requested encounter and tenant, and that the parent encounter is not FINALIZED or SUBMITTED.\n\n### Request guidance\nSend only fields that should change. The schema does not require at least one business field, but every call marks the entry as HUMAN-assigned/human-reviewed in the handler.\n\n### Request notes\n- The lookup scopes by `codedEntryId`, `encounterId`, and parent `billingEncounter.organizationId`.\n- `sequenceNumber` and `poaIndicator` can be set to null where the schema allows.\n- `humanNotes` is capped at 1000 characters.\n\n### Response semantics\nHTTP 200 returns `success: true` with the serialized updated coded-entry record returned by Prisma. The generated OpenAPI schema is generic, so docs should not say the body is empty.\n\n### Response notes\n- Runtime response contains the updated entry fields as serialized by the handler.\n- Because the generic OpenAPI mutation schema does not enumerate those fields, getBillingEncounter is the safest normalized read model.\n\n### Errors and retries\n400 can mean attempting to modify a FINALIZED or SUBMITTED encounter. 404 means the code is missing or not tenant-scoped through the parent encounter. After timeout, read getBillingEncounter before retrying.\n\n### Error notes\n- 400 can mean attempting to modify a FINALIZED or SUBMITTED encounter. 404 means the code is missing or not tenant-scoped through the parent encounter. After timeout, read getBillingEncounter before retrying.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."},{"schema":{"type":"string","minLength":1},"required":true,"name":"codedEntryId","in":"path","description":"Path identifier for the code entry being updated."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":32,"description":"Procedure, revenue, Diagnosis-Related Group (DRG), or other local code on a contract rate schedule row."},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"modifiers":{"type":"array","items":{"type":"string","minLength":1,"maxLength":8},"maxItems":8,"description":"Array of procedure modifiers on a claim line."},"isPrincipal":{"type":"boolean"},"sequenceNumber":{"type":["integer","null"],"exclusiveMinimum":0},"revenueCode":{"type":["string","null"],"maxLength":10,"description":"Nullable institutional revenue code on a claim line."},"units":{"type":"integer","exclusiveMinimum":0},"diagnosisPointers":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"maxItems":12,"description":"Optional diagnosis pointer list, maximum 12 positive integers."},"poaIndicator":{"type":["string","null"],"enum":["Y","N","U","W","1"]},"humanNotes":{"type":"string","maxLength":1000,"description":"Optional reviewer note, maximum 1000 characters."}}},"example":{"code":"ERROR","description":"Example billing_encounter_code note","modifiers":["example-modifiers"],"isPrincipal":true,"sequenceNumber":1,"revenueCode":"example-revenuecode","units":1,"diagnosisPointers":[1]}}},"description":"Send only fields that should change. The schema does not require at least one business field, but every call marks the entry as HUMAN-assigned/human-reviewed in the handler."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}},"delete":{"operationId":"deleteBillingEncounterCode","summary":"Delete billing encounter code","description":"Deletes a code from an editable Billing encounter and records a suppression so reprocessing does not restore it.\n\n### When to use\nUse this when a human reviewer removes an incorrect generated or manual code before finalization.\n\n### Before calling\nConfirm the parent encounter belongs to the tenant and is not FINALIZED or SUBMITTED.\n\n### Request guidance\nPass `encounterId` and `codedEntryId` in the path. No request body is defined.\n\n### Request notes\n- The handler requires code and codeType metadata to record suppression.\n- No body fields are accepted.\n- Suppression is recorded before deletion in the handler test evidence.\n\n### Response semantics\nHTTP 200 returns `success: true` with `codedEntryId`, `deleted: true`, and `suppressed: true` after suppression is recorded and the code is deleted.\n\n### Response notes\n- `deleted` and `suppressed` are both true on successful runtime response.\n- The deleted code body is not returned.\n\n### Errors and retries\n400 can mean the parent encounter is FINALIZED or SUBMITTED. 404 means the code is missing or wrong-tenant. If a timeout occurs, read the encounter code list and suppression/audit context before retrying.\n\n### Error notes\n- 400 can mean the parent encounter is FINALIZED or SUBMITTED. 404 means the code is missing or wrong-tenant. If a timeout occurs, read the encounter code list and suppression/audit context before retrying.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."},{"schema":{"type":"string","minLength":1},"required":true,"name":"codedEntryId","in":"path","description":"Path identifier for the code entry being deleted."}],"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}/physician-queries":{"get":{"operationId":"listBillingPhysicianQueries","summary":"List billing physician queries","description":"Lists physician queries for one Billing encounter in the authenticated organization.\n\n### When to use\nUse this to show outstanding documentation clarification questions, monitor provider responses, or prepare response workflow state for an encounter.\n\n### Before calling\nResolve `encounterId` from tenant-scoped Billing encounter reads.\n\n### Request guidance\nPass `encounterId` in the path. Optional query parameters are `page`, `pageSize`, and `status`; `pageSize` is capped at 100.\n\n### Request notes\n- `status` accepts PENDING, SENT, RESPONDED, RESOLVED, or EXPIRED.\n- The handler first verifies the parent encounter with organizationId.\n\n### Response semantics\nHTTP 200 returns `physicianQueries`, `total`, `page`, `pageSize`, and `totalPages`. Query records include `queryText`, type, status, related code entry, sent/responded/resolved timestamps and IDs, nullable response text, and nullable resolution notes.\n\n### Response notes\n- `queryText` is the billing clarification prompt; treat it as minimum-necessary clinical text and avoid exporting it beyond the workflow need.\n- `responseText` is nullable until a response is recorded.\n- `relatedCodeEntryId` is nullable.\n\n### Errors and retries\n404 means the parent encounter is missing or outside the tenant. Reads can be retried after transient failures.\n\n### Error notes\n- 404 means the parent encounter is missing or outside the tenant. Reads can be retried after transient failures.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."},{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query","description":"One-based COB pagination page number."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"COB pagination page size. Defaults to 25 and is capped at 100 where exposed."},{"schema":{"type":"string","enum":["PENDING","SENT","RESPONDED","RESOLVED","EXPIRED"],"description":"Current billing physician query status."},"required":false,"description":"Current physician query status.","name":"status","in":"query"}],"responses":{"200":{"description":"Physician queries for the billing encounter.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"physicianQueries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"billingEncounterId":{"type":"string"},"queryText":{"type":"string"},"queryType":{"type":"string","enum":["SPECIFICITY","MEDICAL_NECESSITY","CLINICAL_SIGNIFICANCE","CONFLICTING_DOCUMENTATION","MISSING_DOCUMENTATION"],"description":"Billing physician query category."},"relatedCodeEntryId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","SENT","RESPONDED","RESOLVED","EXPIRED"],"description":"Current billing physician query status."},"sentAt":{"type":["string","null"],"format":"date-time"},"sentToProviderId":{"type":["string","null"]},"responseText":{"type":["string","null"]},"respondedAt":{"type":["string","null"],"format":"date-time"},"respondedById":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolutionNotes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","billingEncounterId","queryText","queryType","relatedCodeEntryId","status","sentAt","sentToProviderId","responseText","respondedAt","respondedById","resolvedAt","resolutionNotes","createdAt","updatedAt"]}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["physicianQueries","total","page","pageSize","totalPages"]}},"required":["success","data"]},"example":{"success":true,"data":{"physicianQueries":[{"id":"00000000-0000-4000-8000-000000000001","billingEncounterId":"00000000-0000-4000-8000-000000000001","queryText":"example-querytext","queryType":"SPECIFICITY","relatedCodeEntryId":"00000000-0000-4000-8000-000000000001","status":"PENDING","sentAt":"2026-06-08T10:15:30Z","sentToProviderId":"00000000-0000-4000-8000-000000000001","responseText":"example-responsetext","respondedAt":"2026-06-08T10:15:30Z","respondedById":"00000000-0000-4000-8000-000000000001","resolvedAt":"2026-06-08T10:15:30Z","resolutionNotes":"Example billing_physician_querie note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1,"totalPages":1}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/encounters/{encounterId}/physician-queries/{queryId}/response":{"post":{"operationId":"respondToBillingPhysicianQuery","summary":"Respond to billing physician query","description":"Records a response to a PENDING or SENT Billing physician query through an organization-scoped parent encounter relation.\n\n### When to use\nUse this when a provider or authorized workflow supplies a concise response to a documentation clarification query.\n\n### Before calling\nConfirm the query belongs to the encounter and is still PENDING or SENT. Keep the response limited to the clarification needed for billing review.\n\n### Request guidance\nSend required `responseText` with 1 to 5000 characters. Do not include full transcripts, raw EHR payloads, or unrelated clinical narrative.\n\n### Request notes\n- `responseText` is required and capped at 5000 characters.\n- Only PENDING or SENT queries are eligible according to the handler lookup.\n\n### Response semantics\nHTTP 200 returns `success: true` with the serialized updated physician-query record. The handler sets status to RESPONDED, stores responseText, respondedAt, and respondedById.\n\n### Response notes\n- Runtime response includes the updated query record, not an empty acknowledgement.\n- Status becomes RESPONDED in the handler.\n\n### Errors and retries\n404 can mean the query is missing, wrong-tenant, not tied to the encounter, or no longer PENDING/SENT. After timeout, list queries or read workflow state before retrying.\n\n### Error notes\n- 404 can mean the query is missing, wrong-tenant, not tied to the encounter, or no longer PENDING/SENT. After timeout, list queries or read workflow state before retrying.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"encounterId","in":"path","description":"Encounter identifier supplied as source context for a procedure, charge audit, or operating room log entry. Resolve organization ownership where QuickRCM identifiers are used."},{"schema":{"type":"string","minLength":1},"required":true,"name":"queryId","in":"path","description":"Path identifier for the physician query."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"responseText":{"type":"string","minLength":1,"maxLength":5000,"description":"Required response text, 1 to 5000 characters."}},"required":["responseText"]},"example":{"responseText":"example-responsetext"}}},"description":"Send required `responseText` with 1 to 5000 characters. Do not include full transcripts, raw EHR payloads, or unrelated clinical narrative."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/cdm":{"get":{"operationId":"listBillingCdmEntries","summary":"List billing CDM entries","description":"Lists Charge Description Master entries for the authenticated organization with search and filter controls.\n\n### When to use\nUse this to browse pricing/rate records, resolve CDM IDs before update or deactivate calls, or sync active codes by facility/source/category.\n\n### Before calling\nAuthenticate with `billing:read` or `billing:write`. Decide whether to filter by exact code, active flag, category, source, facility, or free-text search.\n\n### Request guidance\n`page` defaults to 1 and `pageSize` defaults to 25 with maximum 100. `isActive` accepts boolean values and string true/false through preprocessing. `code` is normalized to uppercase exact match; `search` uses code prefix behavior for compact alphanumeric code-like input or case-insensitive code/description contains otherwise.\n\n### Request notes\n- `category` uses the Billing CDM category enum.\n- `source` uses CMS_MPFS, CMS_OPPS, CMS_CLFS, CMS_ASP, CMS_DME, MANUAL, or IMPORT.\n- `facilityId` filters tenant-owned CDM entries by facility reference.\n\n### Response semantics\nHTTP 200 returns `cdmEntries`, `total`, `page`, `pageSize`, and `totalPages`. CDM entries include code, description, type, category, source, active flag, monetary/RVU fields, effective/expiration dates, notes, and timestamps.\n\n### Response notes\n- Decimal-like database values are serialized to numbers or null by the handler.\n- Entries are ordered by `cptHcpcsCode` ascending.\n\n### Errors and retries\nFix invalid enum, boolean, or pagination values after 400. Reads can be retried after transient failures and should back off after 429.\n\n### Error notes\n- Fix invalid enum, boolean, or pagination values after 400. Reads can be retried after transient failures and should back off after 429.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query","description":"One-based COB pagination page number."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"COB pagination page size. Defaults to 25 and is capped at 100 where exposed."},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"search","in":"query","description":"Optional code or description search, maximum 255 characters."},{"schema":{"type":"string","minLength":1,"maxLength":32},"required":false,"name":"code","in":"query","description":"Optional exact CPT/HCPCS code filter, normalized to uppercase."},{"schema":{"type":"string","enum":["EVALUATION_MANAGEMENT","ANESTHESIA","SURGERY","RADIOLOGY","PATHOLOGY_LAB","MEDICINE","CATEGORY_II","CATEGORY_III","HCPCS_DRUGS","HCPCS_DME","HCPCS_AMBULANCE","HCPCS_OTHER"],"description":"Charge Description Master service category."},"required":false,"description":"Product, correspondence, or workflow category used to route and label the record.","name":"category","in":"query"},{"schema":{"type":"string","enum":["CMS_MPFS","CMS_OPPS","CMS_CLFS","CMS_ASP","CMS_DME","MANUAL","IMPORT"],"description":"Source for the Charge Description Master entry."},"required":false,"description":"Short source label for an ADR document reference. Do not place credentials, signed URLs, raw payloads, or storage keys in this field.","name":"source","in":"query"},{"schema":{"type":"boolean"},"required":false,"name":"isActive","in":"query","description":"Optional active/inactive filter; true/false strings are accepted."},{"schema":{"type":"string","minLength":1},"required":false,"name":"facilityId","in":"query","description":"QuickRCM facility identifier scoped to the authenticated organization."}],"responses":{"200":{"description":"Charge Description Master entries for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"cdmEntries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"facilityId":{"type":["string","null"]},"cptHcpcsCode":{"type":"string"},"description":{"type":"string"},"codeType":{"type":"string","enum":["CPT","HCPCS_LEVEL_I","HCPCS_LEVEL_II"],"description":"Charge Description Master code type."},"category":{"type":"string","enum":["EVALUATION_MANAGEMENT","ANESTHESIA","SURGERY","RADIOLOGY","PATHOLOGY_LAB","MEDICINE","CATEGORY_II","CATEGORY_III","HCPCS_DRUGS","HCPCS_DME","HCPCS_AMBULANCE","HCPCS_OTHER"],"description":"Charge Description Master service category."},"source":{"type":"string","enum":["CMS_MPFS","CMS_OPPS","CMS_CLFS","CMS_ASP","CMS_DME","MANUAL","IMPORT"],"description":"Source for the Charge Description Master entry."},"isActive":{"type":"boolean"},"standardCharge":{"type":["number","null"]},"rvuWork":{"type":["number","null"]},"rvuPeFacility":{"type":["number","null"]},"rvuPeNonfacility":{"type":["number","null"]},"rvuMp":{"type":["number","null"]},"conversionFactor":{"type":["number","null"]},"globalPeriod":{"type":["integer","null"]},"bilateralSurgeryIndicator":{"type":"boolean"},"multiProcReductionIndicator":{"type":"boolean"},"pcTcIndicator":{"type":"boolean"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"expirationDate":{"type":["string","null"],"format":"date-time"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","facilityId","cptHcpcsCode","description","codeType","category","source","isActive","standardCharge","rvuWork","rvuPeFacility","rvuPeNonfacility","rvuMp","conversionFactor","globalPeriod","bilateralSurgeryIndicator","multiProcReductionIndicator","pcTcIndicator","effectiveDate","expirationDate","notes","createdAt","updatedAt"]}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["cdmEntries","total","page","pageSize","totalPages"]}},"required":["success","data"]},"example":{"success":true,"data":{"cdmEntries":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","cptHcpcsCode":"example-cpthcpcscode","description":"Example billing_cdm_entrie note","codeType":"CPT","category":"EVALUATION_MANAGEMENT","source":"CMS_MPFS","isActive":true,"standardCharge":125.5,"rvuWork":1.25,"rvuPeFacility":1.25,"rvuPeNonfacility":1.25,"rvuMp":1.25,"conversionFactor":1.25,"globalPeriod":1,"bilateralSurgeryIndicator":true,"multiProcReductionIndicator":true,"pcTcIndicator":true,"effectiveDate":"2026-06-08T10:15:30Z","expirationDate":"2026-06-08T10:15:30Z","notes":"Example billing_cdm_entrie note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1,"totalPages":1}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/cdm/{cdmId}":{"get":{"operationId":"getBillingCdmEntry","summary":"Get billing CDM entry","description":"Returns one organization-owned Charge Description Master entry by CDM ID.\n\n### When to use\nUse this before updating or deactivating a CDM entry, or when a client needs the full current CDM record.\n\n### Before calling\nObtain `cdmId` from listBillingCdmEntries or another trusted QuickRCM handoff.\n\n### Request guidance\nPass `cdmId` in the path. No request body is accepted.\n\n### Request notes\n- Tenant scope is enforced with organizationId in the handler lookup.\n\n### Response semantics\nHTTP 200 returns the mapped CDM entry. Decimal-like fields are converted to numbers when finite or null otherwise.\n\n### Response notes\n- `facilityId`, effective dates, expiration dates, notes, and numeric rate fields are nullable.\n- `isActive` indicates whether the entry is available for use.\n\n### Errors and retries\n404 means the CDM entry is missing or not in the API key organization. Reads can be retried after transient failures.\n\n### Error notes\n- 404 means the CDM entry is missing or not in the API key organization. Reads can be retried after transient failures.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"cdmId","in":"path","description":"Path identifier for the CDM entry."}],"responses":{"200":{"description":"Charge Description Master entry for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"facilityId":{"type":["string","null"]},"cptHcpcsCode":{"type":"string"},"description":{"type":"string"},"codeType":{"type":"string","enum":["CPT","HCPCS_LEVEL_I","HCPCS_LEVEL_II"],"description":"Charge Description Master code type."},"category":{"type":"string","enum":["EVALUATION_MANAGEMENT","ANESTHESIA","SURGERY","RADIOLOGY","PATHOLOGY_LAB","MEDICINE","CATEGORY_II","CATEGORY_III","HCPCS_DRUGS","HCPCS_DME","HCPCS_AMBULANCE","HCPCS_OTHER"],"description":"Charge Description Master service category."},"source":{"type":"string","enum":["CMS_MPFS","CMS_OPPS","CMS_CLFS","CMS_ASP","CMS_DME","MANUAL","IMPORT"],"description":"Source for the Charge Description Master entry."},"isActive":{"type":"boolean"},"standardCharge":{"type":["number","null"]},"rvuWork":{"type":["number","null"]},"rvuPeFacility":{"type":["number","null"]},"rvuPeNonfacility":{"type":["number","null"]},"rvuMp":{"type":["number","null"]},"conversionFactor":{"type":["number","null"]},"globalPeriod":{"type":["integer","null"]},"bilateralSurgeryIndicator":{"type":"boolean"},"multiProcReductionIndicator":{"type":"boolean"},"pcTcIndicator":{"type":"boolean"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"expirationDate":{"type":["string","null"],"format":"date-time"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","facilityId","cptHcpcsCode","description","codeType","category","source","isActive","standardCharge","rvuWork","rvuPeFacility","rvuPeNonfacility","rvuMp","conversionFactor","globalPeriod","bilateralSurgeryIndicator","multiProcReductionIndicator","pcTcIndicator","effectiveDate","expirationDate","notes","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","cptHcpcsCode":"example-cpthcpcscode","description":"Example billing_cdm_entry note","codeType":"CPT","category":"EVALUATION_MANAGEMENT","source":"CMS_MPFS","isActive":true,"standardCharge":125.5,"rvuWork":1.25,"rvuPeFacility":1.25,"rvuPeNonfacility":1.25,"rvuMp":1.25,"conversionFactor":1.25,"globalPeriod":1,"bilateralSurgeryIndicator":true,"multiProcReductionIndicator":true,"pcTcIndicator":true,"effectiveDate":"2026-06-08T10:15:30Z","expirationDate":"2026-06-08T10:15:30Z","notes":"Example billing_cdm_entry note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}},"put":{"operationId":"updateBillingCdmEntry","summary":"Update billing CDM entry","description":"Updates fields on an organization-owned CDM entry and records audit rows for changed fields.\n\n### When to use\nUse this for annual CDM review, rate updates, RVU changes, effective/expiration date changes, note changes, or active-flag corrections.\n\n### Before calling\nRead the CDM entry first and decide which fields should change. Prepare a concise `changeReason` when useful for audit context.\n\n### Request guidance\nSend `updates` with at least one field. Numeric rate/RVU fields must be nonnegative or null where nullable. `effectiveDate` and `expirationDate` are nullable ISO 8601 date-times. `notes` is nullable and capped at 2000 characters; `changeReason` is capped at 500 characters.\n\n### Request notes\n- `updates` must contain at least one field.\n- `standardCharge` changes are audited with action PRICE_CHANGE; other changed fields use UPDATED.\n- Date strings are converted to Date values by the handler for effective/expiration fields.\n\n### Response semantics\nHTTP 200 returns `success: true` with the serialized updated CDM record returned by the handler. The handler also writes CDM audit rows; the response is not an empty acknowledgement.\n\n### Response notes\n- Runtime response contains the updated CDM record.\n- Generated OpenAPI currently uses the generic mutation response schema.\n\n### Errors and retries\n400 can mean `updates` is empty or a field failed validation. 404 means the CDM entry is missing or outside the tenant. After timeout, getBillingCdmEntry before retrying to avoid duplicate audit rows.\n\n### Error notes\n- 400 can mean `updates` is empty or a field failed validation. 404 means the CDM entry is missing or outside the tenant. After timeout, getBillingCdmEntry before retrying to avoid duplicate audit rows.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"cdmId","in":"path","description":"QuickRCM Charge Description Master entry identifier."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"standardCharge":{"type":["number","null"],"minimum":0,"description":"Nullable numeric standard charge on a CDM entry."},"rvuWork":{"type":["number","null"],"minimum":0},"rvuPeFacility":{"type":["number","null"],"minimum":0},"rvuPeNonfacility":{"type":["number","null"],"minimum":0},"rvuMp":{"type":["number","null"],"minimum":0},"conversionFactor":{"type":["number","null"],"minimum":0,"description":"Nullable nonnegative numeric conversion factor."},"globalPeriod":{"type":["integer","null"],"minimum":0,"description":"Nullable nonnegative integer global period."},"bilateralSurgeryIndicator":{"type":"boolean"},"multiProcReductionIndicator":{"type":"boolean"},"pcTcIndicator":{"type":"boolean"},"effectiveDate":{"type":["string","null"],"format":"date-time","description":"ISO datetime when a contract or fee schedule becomes effective."},"expirationDate":{"type":["string","null"],"format":"date-time","description":"Optional coverage expiration date returned as a date-only string or null."},"notes":{"type":["string","null"],"maxLength":2000,"description":"Nullable CDM notes, maximum 2000 characters."},"isActive":{"type":"boolean","description":"Schedule active-state boolean. Schedule create defaults to true; pause/resume endpoints also mutate active state."}},"description":"Object containing one or more CDM fields to change."},"changeReason":{"type":"string","maxLength":500,"description":"Optional audit reason, maximum 500 characters."}},"required":["updates"]},"example":{"updates":{"description":"Example billing_cdm_entry note","standardCharge":125.5,"rvuWork":1.25,"rvuPeFacility":1.25,"rvuPeNonfacility":1.25,"rvuMp":1.25,"conversionFactor":1.25,"globalPeriod":1},"changeReason":"example-changereason"}}},"description":"Send `updates` with at least one field. Numeric rate/RVU fields must be nonnegative or null where nullable. `effectiveDate` and `expirationDate` are nullable ISO 8601 date-times. `notes` is nullable and capped at 2000 characters; `changeReason` is capped at 500 characters."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/cdm/{cdmId}/deactivate":{"post":{"operationId":"deactivateBillingCdmEntry","summary":"Deactivate billing CDM entry","description":"Soft-deactivates an organization-owned CDM entry and records a CDM audit row.\n\n### When to use\nUse this when a CDM entry should no longer be active for billing workflows but should remain historically visible.\n\n### Before calling\nRead the CDM entry and confirm deactivation is intended. Prepare a concise reason if audit context is needed.\n\n### Request guidance\nSend optional `reason` up to 500 characters. The handler sets `isActive` to false and `expirationDate` to the current server time.\n\n### Request notes\n- `reason` is optional and capped at 500 characters.\n- The audit row action is DEACTIVATED.\n\n### Response semantics\nHTTP 200 returns `success: true` with the serialized updated CDM record. The response includes the updated active state returned by the handler, not just a generic acknowledgement.\n\n### Response notes\n- Runtime response contains the updated CDM record.\n- `isActive` is set to false by the handler.\n\n### Errors and retries\n404 means the CDM entry is missing or outside the tenant. After timeout, getBillingCdmEntry before retrying to avoid duplicate audit rows.\n\n### Error notes\n- 404 means the CDM entry is missing or outside the tenant. After timeout, getBillingCdmEntry before retrying to avoid duplicate audit rows.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"cdmId","in":"path","description":"QuickRCM Charge Description Master entry identifier."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Optional deactivation audit reason, maximum 500 characters."}}},"example":{"reason":"example-reason"}}},"description":"Send optional `reason` up to 500 characters. The handler sets `isActive` to false and `expirationDate` to the current server time."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/billing/cdm/import":{"post":{"operationId":"importBillingCdm","summary":"Queue billing CDM import","description":"Queues a CDM rate import for the authenticated organization.\n\n### When to use\nUse this to hand off a bounded set of CDM/rate rows from an external source for asynchronous import.\n\n### Before calling\nPrepare a source label and rate rows with code, description, allowed amount, and optional RVU/global period fields. Use synthetic or system labels, not vendor credentials or raw files.\n\n### Request guidance\nSend `queueOnly: true`, `source` with 1 to 100 characters, and `rates` with 1 to 1000 rows. Each rate requires `code`, `description`, and nonnegative `allowedAmount`; optional RVU fields and `globalPeriod` must be nonnegative when supplied.\n\n### Request notes\n- `rates` minimum is 1 and maximum is 1000.\n- `allowedAmount` is required and nonnegative.\n- `queueOnly` is required and must be true.\n\n### Response semantics\nHTTP 202 returns `queued: true`, `operation: IMPORT_BILLING_CDM`, and nullable `queueJobId`. The import runs asynchronously.\n\n### Response notes\n- Queue acknowledgement uses HTTP 202.\n- Use listBillingCdmEntries or getBillingCdmEntry to inspect imported records after processing.\n\n### Errors and retries\nFix validation errors for row count and nonnegative numeric fields. Reuse `idempotencyKey` when retrying the same import request after a transport failure.\n\n### Error notes\n- Fix validation errors for row count and nonnegative numeric fields. Reuse `idempotencyKey` when retrying the same import request after a transport failure.\n","tags":["Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":255,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."},"source":{"type":"string","minLength":1,"maxLength":100,"description":"Import source label, 1 to 100 characters."},"rates":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":32,"description":"Procedure, revenue, Diagnosis-Related Group (DRG), or other local code on a contract rate schedule row."},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"allowedAmount":{"type":"number","minimum":0,"description":"Required nonnegative allowed amount for a rate row."},"rvuWork":{"type":"number","minimum":0},"rvuPeFacility":{"type":"number","minimum":0},"rvuPeNonfacility":{"type":"number","minimum":0},"rvuMp":{"type":"number","minimum":0},"globalPeriod":{"type":"integer","minimum":0,"description":"Nullable nonnegative integer period field on CDM entries or CDM import rows."}},"required":["code","description","allowedAmount"]},"minItems":1,"maxItems":1000,"description":"CDM rate rows, minimum 1 and maximum 1000."}},"required":["queueOnly","source","rates"]},"example":{"queueOnly":true,"source":"example-source","rates":[{"code":"ERROR","description":"Example import_billing_cdm note","allowedAmount":125.5,"rvuWork":1.25,"rvuPeFacility":1.25,"rvuPeNonfacility":1.25,"rvuMp":1.25,"globalPeriod":1}],"idempotencyKey":"example-idempotencykey"}}},"description":"Send `queueOnly: true`, `source` with 1 to 100 characters, and `rates` with 1 to 1000 rows. Each rate requires `code`, `description`, and nonnegative `allowedAmount`; optional RVU fields and `globalPeriod` must be nonnegative when supplied."},"responses":{"200":{"description":"Billing public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Billing CDM import queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean","enum":[true]},"operation":{"type":"string"},"queueJobId":{"type":["string","null"]}},"required":["queued","operation","queueJobId"]}},"required":["success","data"]},"example":{"success":true,"data":{"queued":true,"operation":"example-operation","queueJobId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/claims":{"get":{"operationId":"listClaims","summary":"List claims","description":"Returns claim records owned by the authenticated organization and lets integrators filter by workflow status, claim type, patient, payer, facility, and service date.\n\n### When to use\nUse this endpoint to build claim worklists, reconcile claim creation with downstream submission tasks, or find claims before opening a detail page.\n\n### Before calling\nAuthenticate with a tenant-scoped API key and decide whether the caller needs a narrow patient, payer, facility, or service-date filter.\n\n### Request guidance\nUse pagination and filters together. Avoid broad unbounded claim searches because claims can include PHI-adjacent workflow context.\n\n### Request notes\n- Use filters to keep the result set relevant.\n- Use pagination for every production list call.\n\n### Response semantics\nThe response is a list of local QuickRCM claim summaries, not proof that a payer accepted or adjudicated the claim.\n\n### Response notes\n- Returned claims are local records.\n- Submission and payer status require separate endpoints.\n\n### Errors and retries\nTreat 401 and 403 as API-key or scope issues, 400 as invalid filters, and 429 as a signal to back off before polling again.\n\n### Error notes\n- Retry 429 with backoff.\n- Do not retry authorization failures without changing credentials.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"skip","in":"query","description":"Number of records to skip for pagination. Use with take when the endpoint exposes skip/take pagination."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"take","in":"query","description":"Maximum number of records to take for skip/take pagination."},{"schema":{"type":"string","enum":["DRAFT","QUEUED","SUBMITTED","ACKNOWLEDGED","IN_PROCESS","PAID","PARTIALLY_PAID","DENIED","REJECTED","VOID"]},"required":false,"name":"status","in":"query","description":"Workflow status filter or target status. Valid values depend on the endpoint schema and module state machine."},{"schema":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"required":false,"name":"claimType","in":"query","description":"Claim form family such as professional, institutional, or dental. The value determines which downstream claim fields are relevant."},{"schema":{"type":"string","minLength":1},"required":false,"name":"patientId","in":"query","description":"QuickRCM patient identifier. The patient must belong to the organization selected by the bearer API key."},{"schema":{"type":"string","minLength":1},"required":false,"name":"payerConfigId","in":"query","description":"QuickRCM payer configuration identifier used for routing, payer metadata, and organization-specific payer settings."},{"schema":{"type":"string","minLength":1},"required":false,"name":"facilityId","in":"query","description":"QuickRCM facility identifier scoped to the authenticated organization."},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"search","in":"query","description":"Free-text search filter. Avoid placing PHI in logs that include search terms."},{"schema":{"type":"string","minLength":1,"description":"Inclusive service start date filter."},"required":false,"description":"Start date for the healthcare service period. Use an ISO date string.","name":"serviceFrom","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Inclusive service end date filter."},"required":false,"description":"End date for the healthcare service period. Use an ISO date string and keep it on or after serviceFrom.","name":"serviceTo","in":"query"}],"responses":{"200":{"description":"Claims for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claims":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["DRAFT","QUEUED","SUBMITTED","ACKNOWLEDGED","IN_PROCESS","PAID","PARTIALLY_PAID","DENIED","REJECTED","VOID"]},"claimControlNumber":{"type":["string","null"]},"totalCharges":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalPaid":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"patientBalance":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"patientId":{"type":["string","null"]},"payerConfigId":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"datesOfServiceStart":{"type":"string","format":"date-time"},"datesOfServiceEnd":{"type":["string","null"],"format":"date-time"},"lineCount":{"type":"integer","minimum":0},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":["string","null"]},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","claimType","status","claimControlNumber","totalCharges","totalPaid","patientBalance","patientId","payerConfigId","facilityId","datesOfServiceStart","datesOfServiceEnd","lineCount","payerConfig","facility","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["claims","total","skip","take"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claims":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"DRAFT","claimControlNumber":"example-claimcontrolnumber","totalCharges":"example-totalcharges","totalPaid":"00000000-0000-4000-8000-000000000001","patientBalance":"example-patientbalance","patientId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","datesOfServiceStart":"2026-06-08T10:15:30Z","datesOfServiceEnd":"2026-06-08T10:15:30Z","lineCount":1,"payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example claim","payerId":"87726"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example claim"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"skip":1,"take":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claims/{claimId}":{"get":{"operationId":"getClaim","summary":"Get claim","description":"Returns a single organization-owned claim with line-level and status-check summary context.\n\n### When to use\nUse this endpoint after a list response, webhook, queue item, or user selection gives you a claimId.\n\n### Before calling\nConfirm the claimId came from the same tenant context as the API key. Cross-organization IDs must return not found or forbidden.\n\n### Request guidance\nPass only the path claimId. Do not include tenant selectors or payer credentials in the request.\n\n### Request notes\n- Use claimId from a trusted QuickRCM response.\n- Never guess claim IDs across tenants.\n\n### Response semantics\nThe response describes the local QuickRCM claim record and related summaries; payer adjudication requires claim status or ERA workflows.\n\n### Response notes\n- Contains local claim state.\n- Does not guarantee payer acceptance.\n\n### Errors and retries\nRetry transient 5xx responses, but treat 404 as an ownership or missing-record outcome unless a prior create response proves the claim exists.\n\n### Error notes\n- 404 can mean missing or wrong organization.\n- 401 and 403 require credential or scope correction.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."}],"responses":{"200":{"description":"Claim detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claim":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["DRAFT","QUEUED","SUBMITTED","ACKNOWLEDGED","IN_PROCESS","PAID","PARTIALLY_PAID","DENIED","REJECTED","VOID"]},"claimControlNumber":{"type":["string","null"]},"totalCharges":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalPaid":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"patientBalance":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"patientId":{"type":["string","null"]},"payerConfigId":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"datesOfServiceStart":{"type":"string","format":"date-time"},"datesOfServiceEnd":{"type":["string","null"],"format":"date-time"},"lineCount":{"type":"integer","minimum":0},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":["string","null"]},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"appointmentId":{"type":["string","null"]},"insuranceId":{"type":["string","null"]},"totalAdjusted":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"placeOfService":{"type":["string","null"]},"diagnosisCodes":{},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"dateOfService":{"type":"string","format":"date-time"},"procedureCode":{"type":"string"},"modifiers":{"type":"array","items":{"type":"string"}},"quantity":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"unitPrice":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"paidAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"adjustedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"patientBalance":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"revenueCode":{"type":["string","null"]},"toothNumber":{"type":["string","null"]},"toothSurface":{"type":["string","null"]},"oralCavityArea":{"type":["string","null"]}},"required":["id","dateOfService","procedureCode","modifiers","quantity","unitPrice","totalAmount","paidAmount","adjustedAmount","patientBalance","revenueCode","toothNumber","toothSurface","oralCavityArea"]}},"statusChecks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"categoryCode":{"type":["string","null"]},"statusCode":{"type":["string","null"]},"message":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","status","categoryCode","statusCode","message","createdAt"]}}},"required":["id","organizationId","claimType","status","claimControlNumber","totalCharges","totalPaid","patientBalance","patientId","payerConfigId","facilityId","datesOfServiceStart","datesOfServiceEnd","lineCount","payerConfig","facility","createdAt","updatedAt","appointmentId","insuranceId","totalAdjusted","placeOfService","lines","statusChecks"]}},"required":["claim"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claim":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"DRAFT","claimControlNumber":"example-claimcontrolnumber","totalCharges":"example-totalcharges","totalPaid":"00000000-0000-4000-8000-000000000001","patientBalance":"example-patientbalance","patientId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","datesOfServiceStart":"2026-06-08T10:15:30Z","datesOfServiceEnd":"2026-06-08T10:15:30Z","lineCount":1,"payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example claim","payerId":"87726"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example claim"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","appointmentId":"00000000-0000-4000-8000-000000000001","insuranceId":"00000000-0000-4000-8000-000000000001","totalAdjusted":"example-totaladjusted","placeOfService":"example-placeofservice","lines":[{"id":"00000000-0000-4000-8000-000000000001","dateOfService":"2026-06-08T10:15:30Z","procedureCode":"example-procedurecode","modifiers":["example-modifiers"],"quantity":"example-quantity","unitPrice":"example-unitprice","totalAmount":"example-totalamount","paidAmount":"example-paidamount","adjustedAmount":"example-adjustedamount","patientBalance":"example-patientbalance","revenueCode":"example-revenuecode","toothNumber":"example-toothnumber","toothSurface":"example-toothsurface","oralCavityArea":"example-oralcavityarea"}],"statusChecks":[{"id":"00000000-0000-4000-8000-000000000001","status":"active","categoryCode":"example-categorycode","statusCode":"example-statuscode","message":"Request failed","createdAt":"2026-06-08T10:15:30Z"}],"diagnosisCodes":"example-diagnosiscodes"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claims/drafts":{"post":{"operationId":"createClaimDraft","summary":"Create claim draft","description":"Creates a local professional, institutional, or dental claim draft for the authenticated organization.\n\n### When to use\nUse this endpoint when your integration is ready to assemble claim data in QuickRCM before validation, submission queueing, or attachment workflows.\n\n### Before calling\nResolve patient, payer, facility, and insurance identifiers from QuickRCM first. The claimType determines which formPayload fields matter.\n\n### Request guidance\nSend synthetic or production-safe claim form data in formPayload. Do not use organizationId as a public tenant selector because the API key already selects the tenant.\n\n### Request notes\n- claimType chooses the claim family.\n- formPayload should match the selected claim family and avoid raw EDI.\n\n### Response semantics\nA successful response creates a local draft claim. It is not a clearinghouse submission and does not create payer acceptance evidence.\n\n### Response notes\n- Returns a local draft claim identifier.\n- Submission happens through submitClaim after review.\n\n### Errors and retries\nFix validation errors before retrying. Use an idempotency strategy around caller-side draft creation if network failures could duplicate drafts.\n\n### Error notes\n- 400 means the draft payload or identifiers are invalid.\n- 404 or 403 means a referenced patient, facility, payer, or insurance record is unavailable to this tenant.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"],"description":"Claim form family such as professional, institutional, or dental. The value determines which downstream claim fields are relevant."},"patientId":{"type":"string","minLength":1,"description":"QuickRCM patient identifier. The patient must belong to the organization selected by the bearer API key."},"facilityId":{"type":"string","minLength":1,"description":"QuickRCM facility identifier scoped to the authenticated organization."},"patientInsuranceId":{"type":"string","minLength":1,"description":"QuickRCM patient insurance record identifier associated with the patient and claim."},"payerConfigId":{"type":"string","minLength":1,"description":"QuickRCM payer configuration identifier used for routing, payer metadata, and organization-specific payer settings."},"formPayload":{"type":"object","additionalProperties":{},"description":"Structured draft-claim payload for the selected claimType. Keep it JSON-native rather than raw X12 EDI."},"lastSubmissionError":{"type":"string","minLength":1,"maxLength":2000,"description":"Most recent submission or validation failure text retained for an internal claim draft. Keep vendor raw payloads out of this value."}},"required":["claimType","patientId","formPayload"]},"example":{"claimType":"PROFESSIONAL","patientId":"00000000-0000-4000-8000-000000000001","formPayload":{},"facilityId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","lastSubmissionError":"example-lastsubmissionerror"}}},"description":"Send synthetic or production-safe claim form data in formPayload. Do not use organizationId as a public tenant selector because the API key already selects the tenant."},"responses":{"201":{"description":"Created draft claim.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["DRAFT"]},"mode":{"type":"string","enum":["created","updated"]}},"required":["claimId","claimType","status","mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"DRAFT","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claims/{claimId}/draft":{"put":{"operationId":"updateClaimDraft","summary":"Update claim draft","description":"Updates an existing local claim draft after QuickRCM verifies that the claim belongs to the authenticated organization.\n\n### When to use\nUse this endpoint to correct claim form data, payer selection, insurance selection, or prior validation errors before queueing submission.\n\n### Before calling\nLoad the current draft with getClaim or an internal workflow, then send only the intended replacement draft fields.\n\n### Request guidance\nUse PUT semantics for the draft update route. Keep lastSubmissionError sanitized and avoid raw payer or clearinghouse payloads.\n\n### Request notes\n- Use claimId in the path to select the draft.\n- Keep formPayload aligned with the claim type.\n\n### Response semantics\nA successful response updates the local draft state. It does not send the claim externally.\n\n### Response notes\n- Returns the updated local claim state.\n- External submission is still a separate queued workflow.\n\n### Errors and retries\nRetry only after checking whether the previous request completed; duplicate draft updates can overwrite user corrections.\n\n### Error notes\n- 409-style conflicts should be handled as stale draft state when exposed.\n- Do not retry malformed formPayload without correction.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"],"description":"Claim form family such as professional, institutional, or dental. The value determines which downstream claim fields are relevant."},"patientId":{"type":"string","minLength":1,"description":"QuickRCM patient identifier. The patient must belong to the organization selected by the bearer API key."},"facilityId":{"type":"string","minLength":1,"description":"QuickRCM facility identifier scoped to the authenticated organization."},"patientInsuranceId":{"type":"string","minLength":1,"description":"QuickRCM patient insurance record identifier associated with the patient and claim."},"payerConfigId":{"type":"string","minLength":1,"description":"QuickRCM payer configuration identifier used for routing, payer metadata, and organization-specific payer settings."},"formPayload":{"type":"object","additionalProperties":{},"description":"Module-specific claim form payload. The required nested fields depend on claimType and should match the generated schema for that claim family."},"lastSubmissionError":{"type":"string","minLength":1,"maxLength":2000,"description":"Most recent submission or validation failure text retained for an internal claim draft. Keep vendor raw payloads out of this value."}},"required":["claimType","patientId","formPayload"]},"example":{"claimType":"PROFESSIONAL","patientId":"00000000-0000-4000-8000-000000000001","formPayload":{},"facilityId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","lastSubmissionError":"example-lastsubmissionerror"}}},"description":"Use PUT semantics for the draft update route. Keep lastSubmissionError sanitized and avoid raw payer or clearinghouse payloads."},"responses":{"200":{"description":"Updated draft claim.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["DRAFT"]},"mode":{"type":"string","enum":["created","updated"]}},"required":["claimId","claimType","status","mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"DRAFT","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Draft claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claims/{claimId}/submit":{"post":{"operationId":"submitClaim","summary":"Submit claim","description":"Queues a safe local claim submission task for a professional, institutional, or dental claim.\n\n### When to use\nUse this after a claim draft has been reviewed and is ready for QuickRCM's submission workflow.\n\n### Before calling\nConfirm the claim is complete, organization-owned, and ready for submission. Use validateOnly or dryRun before production automation.\n\n### Request guidance\nUse queueOnly, validateOnly, or dryRun to control side effects. idempotencyKey should be reused only for the same retry of the same claim submission request.\n\n### Request notes\n- queueOnly is safest for automation pilots.\n- validateOnly checks readiness without creating a task.\n\n### Response semantics\nThe response represents local task creation, validation, or simulation. It is not payer acceptance and not a clearinghouse acknowledgment.\n\n### Response notes\n- 202 or task-like responses mean local workflow accepted.\n- Payer acknowledgments require later status or ERA evidence.\n\n### Errors and retries\nUse idempotencyKey for network retries. Fix validation errors before retrying and back off on 429 responses.\n\n### Error notes\n- 400 indicates claim readiness or request-shape failure.\n- 409 can indicate duplicate idempotency or invalid workflow state when exposed.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."},"validateOnly":{"type":"boolean","default":false,"description":"Validates ownership, authorization, and request shape without creating a task or external submission."},"dryRun":{"type":"boolean","default":false,"description":"Simulates the action without creating a task or making an external submission. Use this to verify request shape safely."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."}}},"example":{"queueOnly":true,"validateOnly":false,"dryRun":false,"idempotencyKey":"example-idempotencykey"}}},"description":"Use queueOnly, validateOnly, or dryRun to control side effects. idempotencyKey should be reused only for the same retry of the same claim submission request."},"responses":{"200":{"description":"Validated or simulated claim submission.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["QUEUED","VALIDATED"]},"taskId":{"type":["string","null"]},"mode":{"type":"string","enum":["queueOnly","validateOnly","dryRun"]},"externalSubmission":{"type":"boolean","enum":[false]}},"required":["claimId","claimType","status","taskId","mode","externalSubmission"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"QUEUED","taskId":"00000000-0000-4000-8000-000000000001","mode":"queueOnly","externalSubmission":false},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Queued local claim submission task.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["QUEUED","VALIDATED"]},"taskId":{"type":["string","null"]},"mode":{"type":"string","enum":["queueOnly","validateOnly","dryRun"]},"externalSubmission":{"type":"boolean","enum":[false]}},"required":["claimId","claimType","status","taskId","mode","externalSubmission"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"QUEUED","taskId":"00000000-0000-4000-8000-000000000001","mode":"queueOnly","externalSubmission":false},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claims/{claimId}/status/check":{"post":{"operationId":"checkClaimStatus","summary":"Check claim status","description":"Queues a safe local claim-status check task for an organization-scoped claim.\n\n### When to use\nUse this when you need a fresh payer or clearinghouse status workflow after claim submission or payer follow-up.\n\n### Before calling\nMake sure the claim exists in QuickRCM and has enough payer/submission context for a status check.\n\n### Request guidance\nUse validateOnly before enabling scheduled polling. Use idempotencyKey to keep repeated status-check requests from creating duplicate local tasks.\n\n### Request notes\n- Use this for workflow initiation, not direct final payer status.\n- dryRun is useful for setup validation.\n\n### Response semantics\nThe response means QuickRCM accepted, validated, or simulated the local status-check workflow; it is not the final 277 status payload.\n\n### Response notes\n- Look for later status records or task completion for results.\n- Response content is local workflow metadata.\n\n### Errors and retries\nBack off on 429 and avoid tight polling loops. Treat 404 as missing or wrong-tenant claim context.\n\n### Error notes\n- Do not retry invalid claim context unchanged.\n- Use idempotencyKey for safe retries after connection failures.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."},"validateOnly":{"type":"boolean","default":false,"description":"Validates ownership, authorization, and request shape without creating a task or external submission."},"dryRun":{"type":"boolean","default":false,"description":"Simulates the action without creating a task or making an external submission. Use this to verify request shape safely."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."}}},"example":{"queueOnly":true,"validateOnly":false,"dryRun":false,"idempotencyKey":"example-idempotencykey"}}},"description":"Use validateOnly before enabling scheduled polling. Use idempotencyKey to keep repeated status-check requests from creating duplicate local tasks."},"responses":{"200":{"description":"Validated or simulated status check.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["QUEUED","VALIDATED"]},"taskId":{"type":["string","null"]},"mode":{"type":"string","enum":["queueOnly","validateOnly","dryRun"]},"externalSubmission":{"type":"boolean","enum":[false]}},"required":["claimId","claimType","status","taskId","mode","externalSubmission"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"QUEUED","taskId":"00000000-0000-4000-8000-000000000001","mode":"queueOnly","externalSubmission":false},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Queued local claim status task.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["QUEUED","VALIDATED"]},"taskId":{"type":["string","null"]},"mode":{"type":"string","enum":["queueOnly","validateOnly","dryRun"]},"externalSubmission":{"type":"boolean","enum":[false]}},"required":["claimId","claimType","status","taskId","mode","externalSubmission"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"QUEUED","taskId":"00000000-0000-4000-8000-000000000001","mode":"queueOnly","externalSubmission":false},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claims/{claimId}/attachments":{"post":{"operationId":"saveClaimAttachment","summary":"Save claim attachment metadata","description":"Stores claim attachment metadata tied to a claim and claim-status context, including payer, patient, subscriber, provider, encounter, and document details.\n\n### When to use\nUse this before uploading or submitting a supporting document for a claim, payer request, status workflow, or additional documentation need.\n\n### Before calling\nVerify the claim and claimStatusId belong to the tenant. Prepare metadata only; binary upload uses the separate attachment-file endpoint.\n\n### Request guidance\nSend metadata fields needed to identify the attachment and its clinical/claim context. Do not embed raw file bytes, signed URLs, or raw EDI.\n\n### Request notes\n- Metadata should identify the payer, patient, subscriber, provider, encounter, and document context.\n- Do not include binary file contents.\n\n### Response semantics\nA successful response creates or updates local attachment metadata. It does not upload a file and does not submit the attachment externally.\n\n### Response notes\n- Returns local attachment metadata.\n- External submission requires submitClaimAttachment after a file exists.\n\n### Errors and retries\nCorrect missing claimStatusId or ownership errors before retrying. File upload failures belong to uploadClaimAttachmentFile, not this metadata endpoint.\n\n### Error notes\n- 400 indicates incomplete or invalid metadata.\n- 403 or 404 means the claim/status context is unavailable to this tenant.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimStatusId":{"type":"string","minLength":1,"description":"QuickRCM claim-status check identifier used to associate attachment metadata with a payer status or request context."},"payer":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"QuickRCM payer configuration identifier returned in a nested payer summary."}},"description":"Payer context used by a claim, attachment, status, or AR workflow."},"submitter":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Identifier from the nested payer, submitter, provider, or product object. Interpret it within that object's context, not globally."},"state":{"type":"string","minLength":1,"maxLength":10,"description":"US state, provider state, submitter state, or workflow state depending on context."}},"description":"Submitter entity context for claim attachment or payer transaction metadata."},"product":{"type":"object","properties":{"type":{"type":"string","minLength":1,"description":"Type discriminator for the surrounding object, such as product type, provider type, queue type, or appeal type."},"category":{"type":"string","minLength":1,"description":"Product, correspondence, or workflow category used to route and label the record."}},"description":"Payer or claim product context for an attachment or claim-related workflow."},"patient":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"description":"Person first name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account."},"lastName":{"type":"string","minLength":1,"description":"Person last name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account."},"dateOfBirth":{"type":"string","minLength":1,"description":"Patient or subscriber date of birth in ISO date format. This is PHI and should only use synthetic values in examples."},"memberNumber":{"type":"string","minLength":1,"description":"Payer subscriber or member identifier. Treat as PHI and avoid logging raw values."},"accountNumber":{"type":"string","minLength":1,"description":"Patient or subscriber account number from the payer, provider, or source workflow. Treat as potentially identifying financial or PHI context."}},"description":"Patient demographic context. Treat nested patient values as PHI and use synthetic examples only."},"subscriber":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"description":"Person first name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account."},"lastName":{"type":"string","minLength":1,"description":"Person last name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account."},"dateOfBirth":{"type":"string","minLength":1,"description":"Patient or subscriber date of birth in ISO date format. This is PHI and should only use synthetic values in examples."},"memberNumber":{"type":"string","minLength":1,"description":"Payer subscriber or member identifier. Treat as PHI and avoid logging raw values."},"accountNumber":{"type":"string","minLength":1,"description":"Patient or subscriber account number from the payer, provider, or source workflow. Treat as potentially identifying financial or PHI context."}},"description":"Insurance subscriber context. Treat nested subscriber values as PHI."},"provider":{"type":"object","properties":{"lastName":{"type":"string","minLength":1,"description":"Person last name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account."},"fullName":{"type":"string","minLength":1,"description":"Full display name for a person or provider. Treat as PHI when linked to a patient or subscriber."},"entityType":{"type":"string","minLength":1,"description":"Provider entity classification, such as individual or organization, when the payer workflow requires it."},"npi":{"type":"string","minLength":1,"description":"National Provider Identifier. Use a valid 10-digit provider NPI when the payer workflow requires provider identity."},"taxId":{"type":"string","minLength":1,"description":"Provider or organization tax identifier. Treat as sensitive and use placeholders in examples."},"type":{"type":"string","minLength":1,"description":"Type discriminator for the surrounding object, such as product type, provider type, queue type, or appeal type."},"state":{"type":"string","minLength":1,"maxLength":10,"description":"US state, provider state, submitter state, or workflow state depending on context."},"zip":{"type":"string","minLength":1,"description":"Postal code for patient, subscriber, or provider address context. Treat as PHI when tied to a person."},"address":{"type":"string","minLength":1,"description":"Street address for the patient, subscriber, provider, or recipient context. Treat address values as PHI when tied to a person."},"city":{"type":"string","minLength":1,"description":"City portion of a patient, subscriber, provider, or recipient address. Treat as PHI when linked to a person."}},"description":"Rendering, billing, or service provider context. Provider identifiers can be sensitive and must be scoped to the organization."},"encounter":{"type":"object","properties":{"serviceFrom":{"type":"string","minLength":1,"description":"Start date for the healthcare service period. Use an ISO date string."},"serviceTo":{"type":"string","minLength":1,"description":"End date for the healthcare service period. Use an ISO date string and keep it on or after serviceFrom."},"requestNumber":{"type":"string","minLength":1,"description":"Payer or internal request number associated with an encounter, authorization, claim status, or attachment workflow."}},"description":"Encounter-level service context that ties claim attachment metadata to service dates, request numbers, or visit details."},"claimNumber":{"type":"string","minLength":1,"description":"Human-facing or payer-facing claim number used for reconciliation. It is not always the same as QuickRCM claimId."},"controlNumber":{"type":"string","minLength":1,"description":"Clearinghouse or transaction control number used to correlate claim, attachment, or status workflow records."},"status":{"type":"string","minLength":1,"description":"Workflow status filter or target status. Valid values depend on the endpoint schema and module state machine."}},"required":["claimStatusId"]},"example":{"claimStatusId":"00000000-0000-4000-8000-000000000001","payer":{"id":"00000000-0000-4000-8000-000000000001"},"submitter":{"id":"00000000-0000-4000-8000-000000000001","state":"example-state"},"product":{"type":"example-type","category":"example-category"},"patient":{"firstName":"John","lastName":"Smith","dateOfBirth":"1984-03-22","memberNumber":"example-membernumber","accountNumber":"example-accountnumber"},"subscriber":{"firstName":"John","lastName":"Smith","dateOfBirth":"1984-03-22","memberNumber":"example-membernumber","accountNumber":"example-accountnumber"},"provider":{"lastName":"Smith","fullName":"Example save_claim_attachment","entityType":"example-entitytype","npi":"1234567893","taxId":"12-3456789","type":"example-type","state":"example-state","zip":"example-zip"},"encounter":{"serviceFrom":"example-servicefrom","serviceTo":"example-serviceto","requestNumber":"example-requestnumber"},"claimNumber":"example-claimnumber"}}},"description":"Send metadata fields needed to identify the attachment and its clinical/claim context. Do not embed raw file bytes, signed URLs, or raw EDI."},"responses":{"200":{"description":"Saved attachment metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":"string"},"claimStatusId":{"type":"string"},"status":{"type":"string","enum":["SAVED"]}},"required":["claimId","claimStatusId","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","claimStatusId":"00000000-0000-4000-8000-000000000001","status":"SAVED"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim or status check not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claims/{claimId}/attachments/files":{"post":{"operationId":"uploadClaimAttachmentFile","summary":"Create attachment file upload","description":"Creates a presigned upload target for a claim attachment file after verifying claim ownership.\n\n### When to use\nUse this after attachment metadata exists and your integration is ready to upload a PDF, image, or other supported document.\n\n### Before calling\nKnow the file name, file size, MIME type, and document type. Keep the actual binary upload separate from metadata creation.\n\n### Request guidance\nRequest an upload target with file metadata only. Do not send file contents to this endpoint.\n\n### Request notes\n- Use fileSize and fileType to validate client-side before upload.\n- Keep presigned upload details out of logs.\n\n### Response semantics\nThe response provides local upload instructions or metadata. Treat any upload URL as sensitive and short-lived.\n\n### Response notes\n- The response is upload setup, not attachment submission.\n- The file still needs the downstream submitClaimAttachment workflow when applicable.\n\n### Errors and retries\nRetry upload-target creation only if you are sure the previous target was not used. Re-request a target after expiration.\n\n### Error notes\n- 400 can mean unsupported file metadata.\n- Expired upload targets should be replaced, not reused.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Original or display name for a file attachment. Do not include PHI beyond what the receiving workflow requires."},"fileType":{"type":"string","minLength":1,"maxLength":255,"description":"MIME type or file classification for an uploaded attachment, such as application/pdf or image/png."},"fileSize":{"type":"integer","minimum":1,"description":"Attachment size in bytes. Enforce upload limits before using the presigned target."},"reasonCode":{"type":"string","minLength":1,"description":"Reason code captured from payer, denial, collection, or appeal workflows. Preserve the source code when available."},"codeType":{"type":"string","minLength":1,"description":"Code set or classification used for a denial, appeal, collection, or claim workflow reason."},"documentType":{"type":["string","null"],"minLength":1,"description":"Attachment or supporting document category, such as medical record, EOB, operative note, or payer form."}},"required":["fileName","fileType","fileSize"]},"example":{"fileName":"Example upload_claim_attachment_file","fileType":"example-filetype","fileSize":1,"reasonCode":"example-reasoncode","codeType":"example-codetype","documentType":"example-documenttype"}}},"description":"Request an upload target with file metadata only. Do not send file contents to this endpoint."},"responses":{"201":{"description":"Created attachment file upload target.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"uploadUrl":{"type":"string"},"fileRecord":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer","minimum":0},"documentType":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","claimId","filename","mimeType","sizeBytes","documentType","createdAt","updatedAt"]}},"required":["uploadUrl","fileRecord"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"uploadUrl":"https://example.quickintell.com/resource","fileRecord":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","filename":"Example upload_claim_attachment_file","mimeType":"example-mimetype","sizeBytes":1,"documentType":"example-documenttype","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claims/{claimId}/attachments/{attachmentId}/submit":{"post":{"operationId":"submitClaimAttachment","summary":"Submit claim attachment","description":"Queues a safe local attachment-submission task for a file associated with an organization-scoped claim.\n\n### When to use\nUse this after attachment metadata and any required file upload are complete.\n\n### Before calling\nConfirm the attachmentId belongs to the claimId in the path and that the uploaded file is ready for submission workflow processing.\n\n### Request guidance\nUse queueOnly, validateOnly, dryRun, and idempotencyKey to avoid accidental duplicate attachment workflow tasks.\n\n### Request notes\n- Path IDs must refer to the same claim attachment relationship.\n- Use dryRun before automated submission workflows.\n\n### Response semantics\nThe response confirms local task queueing, validation, or simulation. It is not payer receipt of the attachment.\n\n### Response notes\n- Local task acceptance is separate from payer attachment acknowledgment.\n- Follow task/status evidence before presenting completion to users.\n\n### Errors and retries\nUse idempotencyKey for safe retries. Treat wrong claim/attachment pairing as a validation or ownership failure.\n\n### Error notes\n- 404 can mean the attachment does not belong to the claim.\n- 429 requires backoff.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."},{"schema":{"type":"string","minLength":1},"required":true,"name":"attachmentId","in":"path","description":"QuickRCM claim attachment file or metadata identifier associated with the claim in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."},"validateOnly":{"type":"boolean","default":false,"description":"Validates ownership, authorization, and request shape without creating a task or external submission."},"dryRun":{"type":"boolean","default":false,"description":"Simulates the action without creating a task or making an external submission. Use this to verify request shape safely."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."}}},"example":{"queueOnly":true,"validateOnly":false,"dryRun":false,"idempotencyKey":"example-idempotencykey"}}},"description":"Use queueOnly, validateOnly, dryRun, and idempotencyKey to avoid accidental duplicate attachment workflow tasks."},"responses":{"200":{"description":"Validated or simulated attachment submission.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":"string"},"attachmentId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["QUEUED","VALIDATED"]},"taskId":{"type":["string","null"]},"mode":{"type":"string","enum":["queueOnly","validateOnly","dryRun"]},"externalSubmission":{"type":"boolean","enum":[false]}},"required":["claimId","attachmentId","claimType","status","taskId","mode","externalSubmission"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","attachmentId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"QUEUED","taskId":"00000000-0000-4000-8000-000000000001","mode":"queueOnly","externalSubmission":false},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Queued local attachment submission task.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":"string"},"attachmentId":{"type":"string"},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL","DENTAL"]},"status":{"type":"string","enum":["QUEUED","VALIDATED"]},"taskId":{"type":["string","null"]},"mode":{"type":"string","enum":["queueOnly","validateOnly","dryRun"]},"externalSubmission":{"type":"boolean","enum":[false]}},"required":["claimId","attachmentId","claimType","status","taskId","mode","externalSubmission"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","attachmentId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"QUEUED","taskId":"00000000-0000-4000-8000-000000000001","mode":"queueOnly","externalSubmission":false},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim or attachment file not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claims/predeterminations":{"post":{"operationId":"submitClaimPredetermination","summary":"Submit claim predetermination","description":"Queues a safe local predetermination workflow for professional or institutional claim-like data.\n\n### When to use\nUse this when a payer predetermination or prospective review is needed before claim submission.\n\n### Before calling\nPrepare the request payload with patient, payer, provider, and service context while keeping it JSON-native and tenant-scoped.\n\n### Request guidance\nUse validateOnly or dryRun first. Predetermination is workflow initiation, not proof of payer decision.\n\n### Request notes\n- Use queueOnly for safe automation pilots.\n- Do not send raw EDI or payer portal credentials.\n\n### Response semantics\nThe response represents local workflow acceptance, validation, or simulation; payer determinations arrive through later workflow evidence.\n\n### Response notes\n- Response is local workflow metadata.\n- A payer decision requires later status or document evidence.\n\n### Errors and retries\nFix validation failures before retrying. Use idempotencyKey for safe retries of the same predetermination request.\n\n### Error notes\n- 400 means request context is incomplete or invalid.\n- Retry transient failures with idempotency when available.\n","tags":["Claims"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL"],"description":"Claim form family such as professional, institutional, or dental. The value determines which downstream claim fields are relevant."},"claimId":{"type":"string","minLength":1,"description":"QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key."},"queueOnly":{"type":"boolean","default":true,"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."},"validateOnly":{"type":"boolean","default":false,"description":"Validates ownership, authorization, and request shape without creating a task or external submission."},"dryRun":{"type":"boolean","default":false,"description":"Simulates the action without creating a task or making an external submission. Use this to verify request shape safely."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."},"payload":{"type":"object","additionalProperties":{},"description":"Structured payload specific to the endpoint action. Use the documented child fields rather than opaque raw vendor payloads."}},"required":["claimType"]},"example":{"claimType":"PROFESSIONAL","claimId":"00000000-0000-4000-8000-000000000001","queueOnly":true,"validateOnly":false,"dryRun":false,"idempotencyKey":"example-idempotencykey","payload":{}}}},"description":"Use validateOnly or dryRun first. Predetermination is workflow initiation, not proof of payer decision."},"responses":{"200":{"description":"Validated or simulated predetermination submission.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":["string","null"]},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL"]},"status":{"type":"string","enum":["QUEUED","VALIDATED"]},"taskId":{"type":["string","null"]},"mode":{"type":"string","enum":["queueOnly","validateOnly","dryRun"]},"externalSubmission":{"type":"boolean","enum":[false]}},"required":["claimId","claimType","status","taskId","mode","externalSubmission"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"QUEUED","taskId":"00000000-0000-4000-8000-000000000001","mode":"queueOnly","externalSubmission":false},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Queued local predetermination task.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claimId":{"type":["string","null"]},"claimType":{"type":"string","enum":["PROFESSIONAL","INSTITUTIONAL"]},"status":{"type":"string","enum":["QUEUED","VALIDATED"]},"taskId":{"type":["string","null"]},"mode":{"type":"string","enum":["queueOnly","validateOnly","dryRun"]},"externalSubmission":{"type":"boolean","enum":[false]}},"required":["claimId","claimType","status","taskId","mode","externalSubmission"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"claimId":"00000000-0000-4000-8000-000000000001","claimType":"PROFESSIONAL","status":"QUEUED","taskId":"00000000-0000-4000-8000-000000000001","mode":"queueOnly","externalSubmission":false},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Claim not found in the authenticated organization when claimId is supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/cob/secondary-claims":{"get":{"operationId":"listCobSecondaryClaims","summary":"List COB secondary claims","description":"Lists local Coordination of Benefits (COB) secondary-claim generation records owned by the organization selected by the bearer API key, with optional status, secondary payer, created-date, and pagination filters.\n\n### When to use\nUse this endpoint to build a COB secondary billing worklist, poll local generation/submission/payment state, or find a secondary claim before opening detail or taking workflow action.\n\n### Before calling\nAuthenticate with an API key that has `cob:read` or `cob:write` scope. Use filters and pagination for production list calls.\n\n### Request guidance\n`page` defaults to 1. `pageSize` defaults to 25 and is capped at 100. `status` must be one of the public `SC_*` secondary-claim statuses. `payerId` filters `secondaryPayerId`. `dateFrom` and `dateTo` filter record creation time and must be either `YYYY-MM-DD` or an ISO datetime with timezone.\n\n### Request notes\n- Use `status`, `payerId`, `dateFrom`, and `dateTo` to avoid broad workflow exports.\n- The API key selects the organization; do not document `organizationId` as a public selector.\n- Date filters accept either date-only values or timezone-qualified ISO datetimes.\n- Coordination of Benefits (COB) status labels are local workflow values, not payer completion guarantees.\n\n### Response semantics\nHTTP 200 returns `data.secondaryClaims`, `total`, `page`, `pageSize`, and `meta.organizationId`. Monetary values are decimal strings or null. The response is local QuickRCM workflow state, not payer acceptance, Electronic Remittance Advice (ERA) posting, or final adjudication evidence.\n\n### Response notes\n- `secondaryClaims` records are local `SecondaryClaimGeneration` summaries.\n- Money fields are strings to preserve decimal precision.\n- Use `getCobSecondaryClaim` for the limited primary claim summary.\n- `organizationId` appears in both row data and response metadata as ownership context selected by the bearer API key.\n\n### Errors and retries\nCorrect 400 validation failures before retrying. Treat 401/403 as credential, scope, or tenant-context problems. Use backoff for 429 responses instead of tight polling.\n\n### Error notes\n- 400 can indicate an invalid status, date filter, page, or pageSize.\n- 429 can be returned by API-key rate limiting.\n- 401 and 403 require credential, scope, or tenant-context correction.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query","description":"One-based page number. Defaults to 1."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"Number of rows per page. Defaults to 25 and cannot exceed 100."},{"schema":{"type":"string","enum":["SC_PENDING_GENERATION","SC_GENERATED","SC_SUBMITTED","SC_ACKNOWLEDGED","SC_PAID","SC_DENIED","SC_CROSSOVER_PENDING","SC_CROSSOVER_SENT","SC_VOID"],"description":"Secondary claim lifecycle status."},"required":false,"description":"Optional secondary-claim lifecycle filter: `SC_PENDING_GENERATION`, `SC_GENERATED`, `SC_SUBMITTED`, `SC_ACKNOWLEDGED`, `SC_PAID`, `SC_DENIED`, `SC_CROSSOVER_PENDING`, `SC_CROSSOVER_SENT`, or `SC_VOID`.","name":"status","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"payerId","in":"query","description":"Optional filter applied to `secondaryPayerId` on local secondary-claim generation records."},{"schema":{"type":"string","minLength":1,"description":"Optional lower created-at bound as YYYY-MM-DD or ISO date-time with timezone."},"required":false,"description":"Optional lower created-at bound as `YYYY-MM-DD` or ISO datetime with timezone.","name":"dateFrom","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Optional upper created-at bound as YYYY-MM-DD or ISO date-time with timezone."},"required":false,"description":"Optional upper created-at bound as `YYYY-MM-DD` or ISO datetime with timezone.","name":"dateTo","in":"query"}],"responses":{"200":{"description":"Secondary claims for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"secondaryClaims":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"primaryClaimId":{"type":"string"},"secondaryClaimId":{"type":["string","null"]},"remittanceId":{"type":["string","null"]},"secondaryPayerId":{"type":["string","null"]},"secondaryPayerName":{"type":["string","null"]},"status":{"type":"string","enum":["SC_PENDING_GENERATION","SC_GENERATED","SC_SUBMITTED","SC_ACKNOWLEDGED","SC_PAID","SC_DENIED","SC_CROSSOVER_PENDING","SC_CROSSOVER_SENT","SC_VOID"],"description":"Secondary claim lifecycle status."},"primaryPaidAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"primaryAllowed":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"secondaryBilledAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"secondaryPaidAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"isCrossover":{"type":"boolean"},"crossoverSource":{"type":["string","null"]},"generatedAt":{"type":["string","null"],"format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","primaryClaimId","secondaryClaimId","remittanceId","secondaryPayerId","secondaryPayerName","status","primaryPaidAmount","primaryAllowed","secondaryBilledAmount","secondaryPaidAmount","isCrossover","crossoverSource","generatedAt","submittedAt","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1}},"required":["secondaryClaims","total","page","pageSize"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"secondaryClaims":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","primaryClaimId":"00000000-0000-4000-8000-000000000001","secondaryClaimId":"00000000-0000-4000-8000-000000000001","remittanceId":"00000000-0000-4000-8000-000000000001","secondaryPayerId":"00000000-0000-4000-8000-000000000001","secondaryPayerName":"Example cob_secondary_claim","status":"SC_PENDING_GENERATION","primaryPaidAmount":"example-primarypaidamount","primaryAllowed":"example-primaryallowed","secondaryBilledAmount":"example-secondarybilledamount","secondaryPaidAmount":"example-secondarypaidamount","isCrossover":true,"crossoverSource":"example-crossoversource","generatedAt":"2026-06-08T10:15:30Z","submittedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/cob/secondary-claims/{secondaryClaimId}":{"get":{"operationId":"getCobSecondaryClaim","summary":"Get COB secondary claim","description":"Returns one organization-owned Coordination of Benefits (COB) secondary-claim generation record plus a public-safe summary of its primary claim when available.\n\n### When to use\nUse this after a list response, generation response, or workflow notification gives you a `secondaryClaimId` and your integration needs detail before submission, payment posting, status checking, or voiding.\n\n### Before calling\nAuthenticate with `cob:read` or `cob:write` scope. Use a `secondaryClaimId` previously returned by COB APIs in the same tenant context.\n\n### Request guidance\nPass only the path `secondaryClaimId`. Do not include payer credentials, raw Electronic Data Interchange (EDI), Protected Health Information (PHI) beyond required identifiers, or tenant selectors in the request.\n\n### Request notes\n- `secondaryClaimId` is required in the path.\n- Use IDs returned from the same organization context.\n- No query parameters are defined for this endpoint.\n\n### Response semantics\nHTTP 200 returns `data.secondaryClaim` and `data.primaryClaim`. The primary claim summary is intentionally limited to id, claim control number, local status, payer name, and line count. It does not include patient demographics, subscriber identifiers, raw remittance detail, raw X12 835 ERA data, or generated X12 837P professional claim payload.\n\n### Response notes\n- `primaryClaim` can be null if the linked primary claim summary is unavailable.\n- `primaryClaim.lineCount` is a count, not line-level claim detail.\n- The response omits raw remittance, raw payer, and raw generated claim payloads.\n- `secondaryClaim.id` is the local generation-row identifier used by subsequent workflow endpoints.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization secondary claim. Retry transient 5xx responses if any are surfaced by infrastructure, but do not retry 401/403 without fixing credentials or scope.\n\n### Error notes\n- 404 means the secondary claim was not found in the authenticated organization.\n- 400 can indicate an invalid or empty path parameter.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"secondaryClaimId","in":"path","description":"Nullable downstream linked secondary-claim identifier inside a secondary-claim response. This differs from the path `secondaryClaimId`, which is the local generation-row `id`; null means no downstream claim record is linked in the public response."}],"responses":{"200":{"description":"Secondary claim detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"secondaryClaim":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"primaryClaimId":{"type":"string"},"secondaryClaimId":{"type":["string","null"]},"remittanceId":{"type":["string","null"]},"secondaryPayerId":{"type":["string","null"]},"secondaryPayerName":{"type":["string","null"]},"status":{"type":"string","enum":["SC_PENDING_GENERATION","SC_GENERATED","SC_SUBMITTED","SC_ACKNOWLEDGED","SC_PAID","SC_DENIED","SC_CROSSOVER_PENDING","SC_CROSSOVER_SENT","SC_VOID"],"description":"Secondary claim lifecycle status."},"primaryPaidAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"primaryAllowed":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"secondaryBilledAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"secondaryPaidAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"isCrossover":{"type":"boolean"},"crossoverSource":{"type":["string","null"]},"generatedAt":{"type":["string","null"],"format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","primaryClaimId","secondaryClaimId","remittanceId","secondaryPayerId","secondaryPayerName","status","primaryPaidAmount","primaryAllowed","secondaryBilledAmount","secondaryPaidAmount","isCrossover","crossoverSource","generatedAt","submittedAt","createdAt","updatedAt"]},"primaryClaim":{"type":["object","null"],"properties":{"id":{"type":"string"},"claimControlNumber":{"type":["string","null"]},"status":{"type":["string","null"]},"payerName":{"type":["string","null"]},"lineCount":{"type":"integer","minimum":0}},"required":["id","claimControlNumber","status","payerName","lineCount"]}},"required":["secondaryClaim","primaryClaim"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"secondaryClaim":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","primaryClaimId":"00000000-0000-4000-8000-000000000001","secondaryClaimId":"00000000-0000-4000-8000-000000000001","remittanceId":"00000000-0000-4000-8000-000000000001","secondaryPayerId":"00000000-0000-4000-8000-000000000001","secondaryPayerName":"Example cob_secondary_claim","status":"SC_PENDING_GENERATION","primaryPaidAmount":"example-primarypaidamount","primaryAllowed":"example-primaryallowed","secondaryBilledAmount":"example-secondarybilledamount","secondaryPaidAmount":"example-secondarypaidamount","isCrossover":true,"crossoverSource":"example-crossoversource","generatedAt":"2026-06-08T10:15:30Z","submittedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"primaryClaim":{"id":"00000000-0000-4000-8000-000000000001","claimControlNumber":"example-claimcontrolnumber","status":"active","payerName":"Example cob_secondary_claim","lineCount":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Secondary claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/cob/orders/{patientId}":{"put":{"operationId":"upsertCobOrder","summary":"Create or update patient COB order","description":"Creates or updates the local payer-order record for one organization-owned patient, including primary, secondary, optional tertiary insurance identifiers and the determination method.\n\n### When to use\nUse this when patient registration, eligibility review, or manual Coordination of Benefits review has established payer order and QuickRCM should store the local payer-order record before secondary opportunity detection or generation.\n\n### Before calling\nAuthenticate with `cob:write` scope. Resolve the patient and insurance identifiers from QuickRCM in the same organization. Supported insurance identifier inputs are organization-scoped payer configuration `id` or `payerId`, the selected patient's `PatientInsurance.id`, or that patient insurance row's linked organization-owned payer configuration `id`, `payerConfigId`, or `payerId`. Confirm the determination method is supported by the public enum.\n\n### Request guidance\n`primaryInsuranceId`, `secondaryInsuranceId`, and `determinationMethod` are required. `tertiaryInsuranceId` is optional. Insurance identifiers are accepted only when they resolve through organization-scoped `PayerConfig.id`/`PayerConfig.payerId`, the selected patient's `PatientInsurance.id`, or that `PatientInsurance` row's linked organization-owned payer configuration identifiers. `notes` is capped at 2000 characters; keep it concise and avoid unnecessary Protected Health Information (PHI). `mspType` is capped at 255 characters when supplied.\n\n### Request notes\n- Accepted insurance identifier sources are organization-scoped `PayerConfig.id`, organization-scoped `PayerConfig.payerId`, the selected patient's `PatientInsurance.id`, or that patient insurance row's linked organization-owned payer configuration identifiers.\n- `isMspApplicable` defaults false when not supplied by the handler path.\n- Use `COB_DET_MANUAL` only when the order was decided outside an automated rule.\n- Do not use payer names, member IDs, or raw eligibility responses as substitutes for these identifier fields.\n\n### Response semantics\nHTTP 200 returns the stored `cobOrder` summary, including payer-order identifiers, determination method/date, Medicare Secondary Payer (MSP) flags, and timestamps. It is a local QuickRCM payer-order record and does not update Electronic Health Record (EHR) insurance slots or submit any claim by itself.\n\n### Response notes\n- `notes` is accepted but not returned in the public response schema.\n- `determinationDate` is set when the record is updated and may be null on create depending on stored data.\n- The response confirms local Coordination of Benefits order storage only.\n\n### Errors and retries\nFix 400 payer-reference or validation failures before retrying. Treat 404 as missing or wrong-tenant patient context. Retry 429 with backoff.\n\n### Error notes\n- 400 can mean a primary, secondary, or tertiary insurance identifier does not resolve for the patient or organization.\n- 404 means the patient was not found in the authenticated organization.\n- 403 can mean missing COB write scope or tenant mismatch.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"patientId","in":"path","description":"QuickRCM patient identifier in the path. The patient must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"primaryInsuranceId":{"type":"string","minLength":1,"description":"Required identifier for the payer/insurance selected as primary. Accepted inputs are an organization-scoped payer configuration `id`/`payerId`, the selected patient's `PatientInsurance.id`, or that row's linked organization-owned payer configuration identifier."},"secondaryInsuranceId":{"type":"string","minLength":1,"description":"Required identifier for the payer/insurance selected as secondary. It follows the same accepted identifier-source rules as `primaryInsuranceId`."},"tertiaryInsuranceId":{"type":"string","minLength":1,"description":"Optional identifier for tertiary coverage tracking. It follows the same accepted identifier-source rules as `primaryInsuranceId`."},"determinationMethod":{"type":"string","enum":["COB_DET_SUBSCRIBER_EMPLOYER","COB_DET_BIRTHDAY_RULE","COB_DET_GENDER_RULE","COB_DET_ACTIVE_INACTIVE","COB_DET_MSP_QUESTIONNAIRE","COB_DET_MANUAL","COB_DET_DEFAULT_ORDER"],"description":"Method used to decide payer order: subscriber/employer, Birthday Rule, gender rule, active/inactive, Medicare Secondary Payer (MSP) questionnaire, manual, or default order."},"isMspApplicable":{"type":"boolean","description":"Optional flag indicating Medicare Secondary Payer (MSP) logic was applicable to the determination."},"mspType":{"type":"string","minLength":1,"maxLength":255,"description":"Optional Medicare Secondary Payer (MSP) type/context label, capped at 255 characters."},"notes":{"type":"string","maxLength":2000,"description":"Optional local determination note, capped at 2000 characters. Avoid unnecessary Protected Health Information (PHI), raw payer text, or credentials."}},"required":["primaryInsuranceId","secondaryInsuranceId","determinationMethod"]},"example":{"primaryInsuranceId":"00000000-0000-4000-8000-000000000001","secondaryInsuranceId":"00000000-0000-4000-8000-000000000001","determinationMethod":"COB_DET_SUBSCRIBER_EMPLOYER","tertiaryInsuranceId":"00000000-0000-4000-8000-000000000001","isMspApplicable":true,"mspType":"example-msptype","notes":"Example upsert_cob_order note"}}},"description":"`primaryInsuranceId`, `secondaryInsuranceId`, and `determinationMethod` are required. `tertiaryInsuranceId` is optional. Insurance identifiers are accepted only when they resolve through organization-scoped `PayerConfig.id`/`PayerConfig.payerId`, the selected patient's `PatientInsurance.id`, or that `PatientInsurance` row's linked organization-owned payer configuration identifiers. `notes` is capped at 2000 characters; keep it concise and avoid unnecessary Protected Health Information (PHI). `mspType` is capped at 255 characters when supplied."},"responses":{"200":{"description":"COB order created or updated for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"cobOrder":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"primaryInsuranceId":{"type":"string"},"secondaryInsuranceId":{"type":"string"},"tertiaryInsuranceId":{"type":["string","null"]},"determinationMethod":{"type":"string","enum":["COB_DET_SUBSCRIBER_EMPLOYER","COB_DET_BIRTHDAY_RULE","COB_DET_GENDER_RULE","COB_DET_ACTIVE_INACTIVE","COB_DET_MSP_QUESTIONNAIRE","COB_DET_MANUAL","COB_DET_DEFAULT_ORDER"],"description":"Method used to determine payer order."},"determinationDate":{"type":["string","null"],"format":"date-time"},"isMspApplicable":{"type":"boolean"},"mspType":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","patientId","primaryInsuranceId","secondaryInsuranceId","tertiaryInsuranceId","determinationMethod","determinationDate","isMspApplicable","mspType","createdAt","updatedAt"]}},"required":["cobOrder"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"cobOrder":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","primaryInsuranceId":"00000000-0000-4000-8000-000000000001","secondaryInsuranceId":"00000000-0000-4000-8000-000000000001","tertiaryInsuranceId":"00000000-0000-4000-8000-000000000001","determinationMethod":"COB_DET_SUBSCRIBER_EMPLOYER","determinationDate":"2026-06-08T10:15:30Z","isMspApplicable":true,"mspType":"example-msptype","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request body or payer references.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/cob/secondary-claim-opportunities/detect":{"post":{"operationId":"detectCobSecondaryClaimOpportunities","summary":"Detect COB secondary claim opportunities","description":"Scans organization-scoped primary remittance data for claims that may need secondary billing and returns sanitized opportunity summaries without patient names, raw X12 835 Electronic Remittance Advice (ERA), or payer payloads.\n\n### When to use\nUse this after primary remittances have been imported and COB orders exist for patients with secondary coverage, before generating individual or batch secondary claims.\n\n### Before calling\nAuthenticate with `cob:write` scope. Ensure Payment Posting/remittance data and COB payer-order records exist for the same organization. Use date and pagination bounds to keep scans small.\n\n### Request guidance\n`page` defaults to 1. `pageSize` defaults to 25 and is capped at 100. `limit` optionally caps returned opportunities and is capped at 100. `dateFrom` and `dateTo` filter remittance check dates and must be `YYYY-MM-DD` or timezone-qualified ISO datetimes. Pagination is over fetched remittances and their remittance-claim rows, not a stable total-opportunity cursor.\n\n### Request notes\n- The scan is side-effect-sensitive enough to require `cob:write` scope.\n- `dateFrom` and `dateTo` are remittance check-date filters, not generated secondary claim dates.\n- The endpoint has a per-organization scan cooldown in addition to API-key rate limiting.\n\n### Response semantics\nHTTP 200 returns `opportunities`, `totalFound`, `scannedRemittances`, and `pagination`. Opportunities include primary claim, remittance, patient id, primary paid/allowed amounts, patient balance, and secondary payer identifiers. `totalFound` is the number of opportunity rows returned from the current scan page after filters and optional `limit`; it is not a guaranteed count of every possible opportunity across all pages. `scannedRemittances` counts remittance-claim rows considered on the current page, and `pagination.hasMore` indicates that another remittance page may exist because the current remittance page reached `pageSize`.\n\n### Response notes\n- `patientBalance` is the candidate secondary-billing balance derived from primary allowed minus primary paid in current implementation evidence.\n- `scannedRemittances` counts remittance-claim rows considered by the scan path for the current page.\n- `totalFound` is the returned opportunity count for this scan page after filters and optional `limit`; it is not an all-pages total.\n- `pagination.hasMore` is true when the fetched remittance page reached `pageSize`, so callers should request the next page to continue scanning.\n- Returned opportunities still need generation before they become local secondary-claim records.\n\n### Errors and retries\nThe operation has API-key rate limits and an organization-level scan cooldown. Back off on 429. Correct invalid body values before retrying 400 responses.\n\n### Error notes\n- 429 can mean API-key rate limit or scan cooldown.\n- 400 can indicate an invalid date filter, page, pageSize, or limit.\n- 403 means missing write scope or tenant authorization failure.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dateFrom":{"type":"string","minLength":1,"description":"Optional lower remittance check-date bound as `YYYY-MM-DD` or ISO datetime with timezone."},"dateTo":{"type":"string","minLength":1,"description":"Optional upper remittance check-date bound as `YYYY-MM-DD` or ISO datetime with timezone."},"page":{"type":"integer","minimum":1,"default":1,"description":"One-based COB pagination page number."},"pageSize":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"COB pagination page size. Defaults to 25 and is capped at 100 where exposed."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"Optional cap on returned opportunities. Minimum 1 and maximum 100."}}},"example":{"dateFrom":"2026-06-08","dateTo":"2026-06-08","page":1,"pageSize":25,"limit":1}}},"description":"`page` defaults to 1. `pageSize` defaults to 25 and is capped at 100. `limit` optionally caps returned opportunities and is capped at 100. `dateFrom` and `dateTo` filter remittance check dates and must be `YYYY-MM-DD` or timezone-qualified ISO datetimes. Pagination is over fetched remittances and their remittance-claim rows, not a stable total-opportunity cursor."},"responses":{"200":{"description":"Detected secondary claim opportunities for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"opportunities":{"type":"array","items":{"type":"object","properties":{"remittanceId":{"type":"string"},"primaryClaimId":{"type":"string"},"patientId":{"type":"string"},"primaryPaid":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"primaryAllowed":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"patientBalance":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"secondaryPayerId":{"type":["string","null"]},"secondaryPayerName":{"type":["string","null"]}},"required":["remittanceId","primaryClaimId","patientId","primaryPaid","primaryAllowed","patientBalance","secondaryPayerId","secondaryPayerName"]}},"totalFound":{"type":"integer","minimum":0},"scannedRemittances":{"type":"integer","minimum":0},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1},"hasMore":{"type":"boolean"}},"required":["page","pageSize","hasMore"]}},"required":["opportunities","totalFound","scannedRemittances","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"opportunities":[{"remittanceId":"00000000-0000-4000-8000-000000000001","primaryClaimId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","primaryPaid":"00000000-0000-4000-8000-000000000001","primaryAllowed":"example-primaryallowed","patientBalance":"example-patientbalance","secondaryPayerId":"00000000-0000-4000-8000-000000000001","secondaryPayerName":"Example detect_cob_secondary_claim_opportunitie"}],"totalFound":1,"scannedRemittances":1,"pagination":{"page":1,"pageSize":1,"hasMore":true}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key or scan rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/cob/secondary-claims/generate":{"post":{"operationId":"generateCobSecondaryClaim","summary":"Generate COB secondary claim","description":"Creates one local secondary-claim generation record from an organization-owned primary claim, matched remittance, and secondary payer identifier after building and validating the internal secondary claim payload.\n\n### When to use\nUse this for a single opportunity after detection or manual review confirms the primary claim/remittance context and secondary payer.\n\n### Before calling\nAuthenticate with `cob:write` scope. Resolve `primaryClaimId`, `remittanceId`, and `secondaryPayerId` from the same organization. Confirm no active non-void secondary claim already exists for the primary claim.\n\n### Request guidance\n`primaryClaimId`, `remittanceId`, and `secondaryPayerId` are required. `secondaryPayerName` is optional and capped at 255 characters. Do not send raw X12 837P professional claim EDI, raw X12 835 ERA data, or payer credentials; the public request only identifies the local source records and secondary payer.\n\n### Request notes\n- Use opportunities returned by `detectCobSecondaryClaimOpportunities` where possible.\n- A non-void existing secondary claim for the same primary claim is a conflict.\n- Do not include raw Electronic Data Interchange (EDI), payer portal material, or payer credentials in this request.\n\n### Response semantics\nHTTP 201 returns the created local `secondaryClaim` summary. The generated internal X12 837P professional claim payload and COB2-style Coordination of Benefits claim-loop context are not returned. `secondaryBilledAmount` is derived from primary allowed minus primary paid in current implementation evidence.\n\n### Response notes\n- New generated records use local `SC_GENERATED` status in current implementation evidence.\n- `secondaryClaimId` can be null until downstream workflow creates or links another claim record.\n- The response is local generation evidence, not clearinghouse submission, payer acceptance, or adjudication.\n\n### Errors and retries\n400 can mean validation failure for the generated secondary claim. 404 can mean missing primary claim or remittance claim context in the organization. 409 means a non-void secondary claim already exists for the primary claim. For uncertain network outcomes, read by primary claim/list before retrying to avoid duplicate creation.\n\n### Error notes\n- 409 should be handled by reading the existing secondary-claim queue/detail rather than blindly retrying.\n- 400 can include generated-claim validation failures.\n- 404 can indicate the remittance claim is missing or wrong-tenant even when the primary claim id exists elsewhere.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"primaryClaimId":{"type":"string","minLength":1,"description":"Required QuickRCM primary claim identifier. It must belong to the authenticated organization."},"remittanceId":{"type":"string","minLength":1,"description":"QuickRCM remittance identifier used as primary adjudication context. It refers to local remittance data, not a raw X12 835 ERA payload."},"secondaryPayerId":{"type":"string","minLength":1,"description":"Required secondary payer identifier used for the generated local secondary claim."},"secondaryPayerName":{"type":"string","minLength":1,"maxLength":255,"description":"Optional display name for the secondary payer, capped at 255 characters."}},"required":["primaryClaimId","remittanceId","secondaryPayerId"]},"example":{"primaryClaimId":"00000000-0000-4000-8000-000000000001","remittanceId":"00000000-0000-4000-8000-000000000001","secondaryPayerId":"00000000-0000-4000-8000-000000000001","secondaryPayerName":"Example cob_secondary_claim"}}},"description":"`primaryClaimId`, `remittanceId`, and `secondaryPayerId` are required. `secondaryPayerName` is optional and capped at 255 characters. Do not send raw X12 837P professional claim EDI, raw X12 835 ERA data, or payer credentials; the public request only identifies the local source records and secondary payer."},"responses":{"201":{"description":"Secondary claim generated for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"secondaryClaim":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"primaryClaimId":{"type":"string"},"secondaryClaimId":{"type":["string","null"]},"remittanceId":{"type":["string","null"]},"secondaryPayerId":{"type":["string","null"]},"secondaryPayerName":{"type":["string","null"]},"status":{"type":"string","enum":["SC_PENDING_GENERATION","SC_GENERATED","SC_SUBMITTED","SC_ACKNOWLEDGED","SC_PAID","SC_DENIED","SC_CROSSOVER_PENDING","SC_CROSSOVER_SENT","SC_VOID"],"description":"Secondary claim lifecycle status."},"primaryPaidAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"primaryAllowed":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"secondaryBilledAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"secondaryPaidAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"isCrossover":{"type":"boolean"},"crossoverSource":{"type":["string","null"]},"generatedAt":{"type":["string","null"],"format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","primaryClaimId","secondaryClaimId","remittanceId","secondaryPayerId","secondaryPayerName","status","primaryPaidAmount","primaryAllowed","secondaryBilledAmount","secondaryPaidAmount","isCrossover","crossoverSource","generatedAt","submittedAt","createdAt","updatedAt"]}},"required":["secondaryClaim"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"secondaryClaim":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","primaryClaimId":"00000000-0000-4000-8000-000000000001","secondaryClaimId":"00000000-0000-4000-8000-000000000001","remittanceId":"00000000-0000-4000-8000-000000000001","secondaryPayerId":"00000000-0000-4000-8000-000000000001","secondaryPayerName":"Example cob_secondary_claim","status":"SC_PENDING_GENERATION","primaryPaidAmount":"example-primarypaidamount","primaryAllowed":"example-primaryallowed","secondaryBilledAmount":"example-secondarybilledamount","secondaryPaidAmount":"example-secondarypaidamount","isCrossover":true,"crossoverSource":"example-crossoversource","generatedAt":"2026-06-08T10:15:30Z","submittedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request body or generated claim validation failure.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Primary claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"A secondary claim already exists for this primary claim.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/cob/secondary-claims/batch-generate":{"post":{"operationId":"batchGenerateCobSecondaryClaims","summary":"Batch generate COB secondary claims","description":"Attempts to generate local secondary-claim records for 1 to 50 supplied opportunities and returns aggregate counts plus per-primary-claim success or error outcomes.\n\n### When to use\nUse this after detection and review when an integration wants to turn multiple opportunity summaries into local secondary-claim records in one call.\n\n### Before calling\nAuthenticate with `cob:write` scope. Deduplicate opportunities client-side and keep each item tied to source IDs from the same organization.\n\n### Request guidance\n`opportunities` is required and must contain at least 1 and at most 50 entries. Each entry requires `primaryClaimId`, `remittanceId`, and `secondaryPayerId`; `secondaryPayerName` is optional and capped at 255 characters.\n\n### Request notes\n- Batch size is capped at 50 opportunities.\n- The endpoint may partially succeed; item-level failures are returned in `results`.\n- Do not send patient demographics, raw remittance, raw Electronic Data Interchange (EDI), X12 835 ERA payloads, or X12 837P claim payloads in opportunity objects.\n\n### Response semantics\nHTTP 200 can include both successes and failures. `successCount`, `errorCount`, and `totalProcessed` summarize the batch. `results` reports each `primaryClaimId`, whether that item succeeded, and an error string when it failed. The response does not return created secondary-claim IDs, raw X12 837P payloads, raw X12 835 ERA data, or COB2-style claim-loop payloads.\n\n### Response notes\n- `totalProcessed` equals the number of submitted opportunity objects.\n- `error` is null for successful result entries.\n- Read the secondary-claim list/detail endpoints after success if you need generated record IDs.\n\n### Errors and retries\nFix request-shape failures before retrying 400 responses. For item-level failures in a 200 response, inspect `results` and retry only corrected failed opportunities. Use backoff for 429.\n\n### Error notes\n- 400 can indicate an empty batch or more than 50 opportunities.\n- Per-item duplicate, missing claim, missing remittance, or validation failures are returned in `results` with HTTP 200.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"opportunities":{"type":"array","items":{"type":"object","properties":{"primaryClaimId":{"type":"string","minLength":1,"description":"QuickRCM primary claim identifier used for secondary opportunity, generation, and batch generation workflows. It must belong to the API key organization."},"remittanceId":{"type":"string","minLength":1,"description":"QuickRCM remittance identifier used as primary adjudication context for opportunity detection and secondary generation. It does not expose raw X12 835 ERA data."},"secondaryPayerId":{"type":"string","minLength":1,"description":"Required secondary payer/insurance identifier for generation workflows and optional list filter through `payerId`."},"secondaryPayerName":{"type":"string","minLength":1,"maxLength":255,"description":"Optional display name for the secondary payer, capped at 255 characters where accepted."}},"required":["primaryClaimId","remittanceId","secondaryPayerId"]},"minItems":1,"maxItems":50,"description":"Array of 1 to 50 secondary-claim generation inputs."}},"required":["opportunities"]},"example":{"opportunities":[{"primaryClaimId":"00000000-0000-4000-8000-000000000001","remittanceId":"00000000-0000-4000-8000-000000000001","secondaryPayerId":"00000000-0000-4000-8000-000000000001","secondaryPayerName":"Example batch_generate_cob_secondary_claim"}]}}},"description":"`opportunities` is required and must contain at least 1 and at most 50 entries. Each entry requires `primaryClaimId`, `remittanceId`, and `secondaryPayerId`; `secondaryPayerName` is optional and capped at 255 characters."},"responses":{"200":{"description":"Batch generation result counts and per-claim outcomes.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"successCount":{"type":"integer","minimum":0},"errorCount":{"type":"integer","minimum":0},"totalProcessed":{"type":"integer","minimum":0},"results":{"type":"array","items":{"type":"object","properties":{"primaryClaimId":{"type":"string"},"success":{"type":"boolean"},"error":{"type":["string","null"]}},"required":["primaryClaimId","success","error"]}}},"required":["successCount","errorCount","totalProcessed","results"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"successCount":1,"errorCount":1,"totalProcessed":1,"results":[{"primaryClaimId":"00000000-0000-4000-8000-000000000001","success":true,"error":"Request failed"}]},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/cob/secondary-claims/{secondaryClaimId}/submit":{"post":{"operationId":"submitCobSecondaryClaim","summary":"Queue COB secondary claim submission","description":"Initiates the public secondary-claim submission workflow for a generated local secondary claim and returns queue/submission tracking metadata without exposing the claim payload.\n\n### When to use\nUse this only after a secondary claim has been generated, reviewed, and is ready for configured submission workflow.\n\n### Before calling\nAuthenticate with `cob:write` scope. Confirm the secondary claim belongs to the organization and is in `SC_GENERATED` state. Provide the required `queueOnly: true` safety flag.\n\n### Request guidance\nThe body requires `queueOnly` and the only allowed value is true. The path `secondaryClaimId` is required. Do not send raw X12 837P professional claim EDI, payer credentials, or a request to force direct payer submission.\n\n### Request notes\n- `queueOnly` must be true in the public schema.\n- The endpoint is side-effect-sensitive and requires COB write scope.\n- Use generated secondary claim IDs from COB APIs; do not guess IDs across tenants.\n\n### Response semantics\nHTTP 202 returns `{ queued: true, submissionId }` and `meta.organizationId`. It confirms QuickRCM accepted the workflow request. It is not payer acceptance, a clearinghouse acknowledgment, final adjudication, or proof of externally delivered Electronic Data Interchange (EDI). The success path is live-side-effect-sensitive and should not be used as a live smoke test without an approved clearinghouse sandbox and synthetic data.\n\n### Response notes\n- `queued: true` means the public workflow request was accepted by QuickRCM.\n- `submissionId` can be null.\n- Do not interpret 202 as clearinghouse acceptance or payer adjudication.\n- The example is illustrative only and should not be used as a live smoke test because the success path can route toward clearinghouse submission.\n\n### Errors and retries\n400 can indicate invalid body or an invalid current secondary-claim status. 404 means missing or wrong-tenant secondary claim. 502 means the submission workflow failed before a successful public response. For timeouts, read secondary-claim detail before retrying.\n\n### Error notes\n- 400 can mean the claim is not in a submittable local status.\n- 502 indicates the submission workflow failed.\n- The success path has been classified unsafe for automated live tests because it can route toward clearinghouse submission.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"secondaryClaimId","in":"path","description":"QuickRCM secondary-claim generation identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"description":"Required safety flag. Public schema permits only `true`."}},"required":["queueOnly"]},"example":{"queueOnly":true}}},"description":"The body requires `queueOnly` and the only allowed value is true. The path `secondaryClaimId` is required. Do not send raw X12 837P professional claim EDI, payer credentials, or a request to force direct payer submission."},"responses":{"202":{"description":"Secondary claim submission workflow queued locally.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean","enum":[true]},"submissionId":{"type":["string","null"]}},"required":["queued","submissionId"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"submissionId":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request body or claim status.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Secondary claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"502":{"description":"Submission queue workflow failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":502}}}}}}},"/api/v1/cob/secondary-claims/{secondaryClaimId}/status/check":{"post":{"operationId":"checkCobSecondaryClaimStatus","summary":"Check COB secondary claim status","description":"Returns the current local secondary-claim status for an organization-owned secondary claim that is already submitted or acknowledged.\n\n### When to use\nUse this to refresh local Coordination of Benefits workflow status after submission workflow, without requesting raw payer status payloads.\n\n### Before calling\nAuthenticate with `cob:read` or `cob:write` scope. Confirm the secondary claim exists in the same tenant and is in a status eligible for local status check.\n\n### Request guidance\nPass the required path `secondaryClaimId`. The request body is an empty object in the public schema. Do not send payer credentials or raw X12 276/277 claim-status EDI payload requests.\n\n### Request notes\n- The public body has no fields.\n- Only submitted or acknowledged local secondary claims are eligible in current implementation evidence.\n- This endpoint is a local status refresh, not a payer status transaction response.\n\n### Response semantics\nHTTP 200 returns `status` and `lastChecked`. Current implementation evidence returns the stored local status and a fresh timestamp; it does not return an X12 277 claim-status response, payer message, or clearinghouse payload.\n\n### Response notes\n- `status` is one of the public `SC_*` secondary-claim statuses.\n- `lastChecked` is a date-time or null.\n- No raw clearinghouse or payer status payload is returned.\n\n### Errors and retries\n400 can indicate the claim is not in `SC_SUBMITTED` or `SC_ACKNOWLEDGED`. 404 means missing or wrong-tenant secondary claim. Back off on 429.\n\n### Error notes\n- 400 can mean the secondary claim is in a generated, paid, denied, void, or crossover status that is not eligible for status check.\n- 404 means missing or wrong organization.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"secondaryClaimId","in":"path","description":"Path identifier for an existing local `SecondaryClaimGeneration` row on detail, submit, status, payment, and void endpoints. The same field name can be null inside a secondary-claim response when no downstream linked claim id exists."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"Pass the required path `secondaryClaimId`. The request body is an empty object in the public schema. Do not send payer credentials or raw X12 276/277 claim-status EDI payload requests."},"responses":{"200":{"description":"Current local secondary claim status.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["SC_PENDING_GENERATION","SC_GENERATED","SC_SUBMITTED","SC_ACKNOWLEDGED","SC_PAID","SC_DENIED","SC_CROSSOVER_PENDING","SC_CROSSOVER_SENT","SC_VOID"],"description":"Secondary claim lifecycle status."},"lastChecked":{"type":["string","null"],"format":"date-time"}},"required":["status","lastChecked"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"status":"SC_PENDING_GENERATION","lastChecked":"2026-06-08T10:15:30Z"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters or claim status.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Secondary claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/cob/secondary-claims/{secondaryClaimId}/payments":{"post":{"operationId":"postCobSecondaryPayment","summary":"Post COB secondary payment","description":"Updates the local secondary-claim record with a secondary paid amount and derives a local paid-or-denied status.\n\n### When to use\nUse this after secondary adjudication/payment information has been reviewed and the integration needs to update QuickRCM local Coordination of Benefits workflow state.\n\n### Before calling\nAuthenticate with `cob:write` scope. Confirm the secondary claim belongs to the organization and is in `SC_SUBMITTED` or `SC_ACKNOWLEDGED` status.\n\n### Request guidance\n`paidAmount` is required, is accepted as a JSON number by the public schema, and must be zero or greater. `remittanceReference` and `adjustments` are accepted by the public schema, but current public handler evidence forwards only `paidAmount` into the local update path; avoid promising durable effects for those optional fields until implementation changes.\n\n### Request notes\n- Use decimal-safe handling around `paidAmount` even though the public schema exposes a JSON number.\n- `remittanceReference` is capped at 255 characters when supplied.\n- `adjustments` should not contain raw X12 835 ERA payloads, Protected Health Information (PHI), or payer portal text.\n- A zero-dollar `paidAmount` is local denial-state evidence in current implementation, not proof of payer denial content.\n\n### Response semantics\nHTTP 200 returns `{ success, newStatus }`. Current public handler evidence sets `SC_PAID` when `paidAmount` is greater than zero and `SC_DENIED` when it is zero. This is local Coordination of Benefits workflow state, not cash posting, Electronic Remittance Advice (ERA) import, patient accounts receivable balance transfer, or payer remittance storage.\n\n### Response notes\n- `newStatus` is local `SC_PAID` or `SC_DENIED` in current public handler evidence.\n- The response does not include a payment ID, ERA ID, patient AR update, or cash posting receipt.\n- Optional adjustment/reference fields are not evidenced as durably stored by the public handler.\n\n### Errors and retries\n400 can indicate invalid amount or claim status. 404 means missing or wrong-tenant secondary claim. For ambiguous network outcomes, read detail before retrying to avoid duplicate audit/update attempts.\n\n### Error notes\n- 400 can mean the claim is not submitted or acknowledged.\n- 404 means the secondary claim was not found in the authenticated organization.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"secondaryClaimId","in":"path","description":"Path identifier for an existing local `SecondaryClaimGeneration` row on detail, submit, status, payment, and void endpoints. The same field name can be null inside a secondary-claim response when no downstream linked claim id exists."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"paidAmount":{"type":["number","null"],"minimum":0,"description":"Required non-negative secondary paid amount accepted as a JSON number. Current public handler maps values greater than zero to `SC_PAID` and zero to `SC_DENIED`."},"remittanceReference":{"type":"string","minLength":1,"maxLength":255,"description":"Optional reference string accepted by the schema and capped at 255 characters; durable public-handler effect is not evidenced."},"adjustments":{"type":"object","additionalProperties":{"type":["number","null"]},"description":"Optional object of numeric adjustment values accepted by the schema; do not include raw X12 835 ERA payloads, and durable public-handler effect is not evidenced."}},"required":["paidAmount"]},"example":{"paidAmount":125.5,"remittanceReference":"example-remittancereference","adjustments":{}}}},"description":"`paidAmount` is required, is accepted as a JSON number by the public schema, and must be zero or greater. `remittanceReference` and `adjustments` are accepted by the public schema, but current public handler evidence forwards only `paidAmount` into the local update path; avoid promising durable effects for those optional fields until implementation changes."},"responses":{"200":{"description":"Secondary payment posting result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"success":{"type":"boolean"},"newStatus":{"type":"string","enum":["SC_PENDING_GENERATION","SC_GENERATED","SC_SUBMITTED","SC_ACKNOWLEDGED","SC_PAID","SC_DENIED","SC_CROSSOVER_PENDING","SC_CROSSOVER_SENT","SC_VOID"],"description":"Secondary claim lifecycle status."}},"required":["success","newStatus"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"success":true,"newStatus":"SC_PENDING_GENERATION"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request body or claim status.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Secondary claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/cob/secondary-claims/{secondaryClaimId}/void":{"put":{"operationId":"voidCobSecondaryClaim","summary":"Void COB secondary claim","description":"Voids a non-paid local secondary-claim record for the authenticated organization and records the local workflow transition.\n\n### When to use\nUse this when a generated, submitted, acknowledged, denied, or other non-paid local secondary-claim workflow should no longer be active in QuickRCM.\n\n### Before calling\nAuthenticate with `cob:write` scope. Confirm the secondary claim belongs to the organization and is not already paid or voided.\n\n### Request guidance\n`reason` is required, must be non-empty, and is capped at 2000 characters. Keep it operational and avoid unnecessary Protected Health Information (PHI), raw Electronic Data Interchange (EDI), payer portal text, or credentials.\n\n### Request notes\n- Paid claims cannot be voided through this endpoint in current implementation evidence.\n- Already voided claims are rejected.\n- Use concise local workflow reasons rather than raw payer text.\n\n### Response semantics\nHTTP 200 returns `{ success: true }` and `meta.organizationId`. It confirms local void state only. It does not send a payer reversal, reverse a payment, update patient accounts receivable, or void an external clearinghouse claim by itself.\n\n### Response notes\n- `success: true` confirms local void state.\n- The response does not include an external reversal confirmation.\n- Read detail/list after voiding to observe local `SC_VOID` state.\n\n### Errors and retries\n400 can indicate missing reason, paid claim, already voided claim, or other invalid status. 404 means missing or wrong-tenant secondary claim. For ambiguous timeouts, read detail before retrying.\n\n### Error notes\n- 400 can mean the claim is paid or already voided.\n- 404 means missing or wrong organization.\n","tags":["Coordination of Benefits"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"secondaryClaimId","in":"path","description":"Path identifier for an existing local `SecondaryClaimGeneration` row on detail, submit, status, payment, and void endpoints. The same field name can be null inside a secondary-claim response when no downstream linked claim id exists."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Required local void reason, capped at 2000 characters."}},"required":["reason"]},"example":{"reason":"example-reason"}}},"description":"`reason` is required, must be non-empty, and is capped at 2000 characters. Keep it operational and avoid unnecessary Protected Health Information (PHI), raw Electronic Data Interchange (EDI), payer portal text, or credentials."},"responses":{"200":{"description":"Secondary claim void result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"success":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request body or claim status.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Secondary claim not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/collections/agencies":{"get":{"operationId":"listCollectionAgencies","summary":"List collection agencies","description":"Lists collection agency records owned by the organization selected by the bearer API key, with optional agency status and skip/take pagination.\n\n### When to use\nUse this endpoint to populate agency selectors, reconcile configured recovery partners, monitor agency-level recovery metrics, or find an agency before creating local placement records.\n\n### Before calling\nAuthenticate with an API key that has `collections:read` or `collections:write`. Choose an optional `status` filter and bounded pagination.\n\n### Request guidance\n`status` must be one of `CA_ACTIVE`, `CA_INACTIVE`, `CA_SUSPENDED`, or `CA_TERMINATED`. `skip` defaults to 0. `take` defaults to 25 and is capped at 100. Do not send `organizationId`; the bearer API key supplies tenant context.\n\n### Request notes\n- Use `status=CA_ACTIVE` when selecting an agency for new placement work.\n- Avoid logging raw query strings if surrounding application logs may include agency names or contact metadata.\n- List/get endpoints accept read or write Collections scopes.\n\n### Response semantics\nThe response returns `data.agencies`, `total`, `skip`, and `take`. Agency rows include local contact/configuration fields, commission and recovery metrics as strings where applicable, and `recentPlacements` rollups. They do not prove external agency availability.\n\n### Response notes\n- `recentPlacements` contains placement id, status, totalBalance, and recoveredAmount rollups only.\n- `commissionRate`, `totalRecovered`, and `recoveryRate` are serialized as strings.\n- Use getCollectionAgency for a single agency record by id.\n\n### Errors and retries\nTreat 400 as invalid enum or pagination input, 401 as missing or invalid credentials, 403 as insufficient Collections scope or tenant authorization, and 429 as the shared public API rate limit of 60 requests per minute. Retry transient 5xx responses with normal client retry limits.\n\n### Error notes\n- 400 can indicate an invalid agency status or pagination value.\n- 403 means the bearer key does not authorize Collections access for this organization.\n- 429 should be retried with backoff rather than tight polling.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]},"required":false,"name":"status","in":"query","description":"Optional agency status filter. Valid values are `CA_ACTIVE`, `CA_INACTIVE`, `CA_SUSPENDED`, and `CA_TERMINATED`."},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"skip","in":"query","description":"Zero-based number of agency rows to skip. Defaults to 0."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"take","in":"query","description":"Maximum agency rows to return. Defaults to 25 and cannot exceed 100."}],"responses":{"200":{"description":"Collection agencies for the authenticated organization","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"agencies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"contactName":{"type":["string","null"]},"contactEmail":{"type":["string","null"]},"contactPhone":{"type":["string","null"]},"address":{"type":["string","null"]},"status":{"type":"string","enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]},"commissionRate":{"type":"string"},"contractStartDate":{"type":["string","null"],"format":"date-time"},"contractEndDate":{"type":["string","null"],"format":"date-time"},"totalPlaced":{"type":"integer"},"totalRecovered":{"type":"string"},"recoveryRate":{"type":"string"},"avgDaysToRecover":{"type":["integer","null"]},"recentPlacements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"}},"required":["id","status","totalBalance","recoveredAmount"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","contactName","contactEmail","contactPhone","address","status","commissionRate","contractStartDate","contractEndDate","totalPlaced","totalRecovered","recoveryRate","avgDaysToRecover","recentPlacements","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["agencies","total","skip","take"]}},"required":["success","data"]},"example":{"success":true,"data":{"agencies":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example collection_agencie","contactName":"Example collection_agencie","contactEmail":"developer@example.com","contactPhone":"+15551234567","address":"example-address","status":"CA_ACTIVE","commissionRate":"example-commissionrate","contractStartDate":"2026-06-08T10:15:30Z","contractEndDate":"2026-06-08T10:15:30Z","totalPlaced":1,"totalRecovered":"example-totalrecovered","recoveryRate":"example-recoveryrate","avgDaysToRecover":1,"recentPlacements":[{"id":"00000000-0000-4000-8000-000000000001","status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount"}],"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"skip":1,"take":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createCollectionAgency","summary":"Create collection agency","description":"Creates a local collection agency record inside the authenticated organization.\n\n### When to use\nUse this during implementation or onboarding when QuickRCM needs a configured recovery partner before placement records can reference that agency.\n\n### Before calling\nAuthenticate with `collections:write`. Decide the agency display name and commission rate; add only operational contact information needed for staff workflow.\n\n### Request guidance\n`name` and `commissionRate` are required. `commissionRate` is a number from 0 through 100. Contact fields and address are optional. `contractStartDate` and `contractEndDate` are optional non-empty strings in the OpenAPI schema, and the runtime create path rejects invalid date strings and rejects a start date that is on or after the end date when both are supplied.\n\n### Request notes\n- `name` is capped at 200 characters.\n- `contactEmail` must be a valid email when provided.\n- Use consistent ISO date or datetime strings for contract dates.\n- Do not store payer portal credentials, API tokens, or unnecessary Protected Health Information (PHI) in agency contact fields.\n\n### Response semantics\nA 201 response returns the created local agency record. New agencies are created with local status `CA_ACTIVE`. This does not initiate placement transmission, confirm an external agency contract, or test agency connectivity.\n\n### Response notes\n- The response contains local agency configuration and initialized metrics.\n- New placements are created through createBadDebtPlacements.\n- The response is not external agency acceptance or connectivity evidence.\n\n### Errors and retries\nFix 400 validation failures before retrying. After a timeout, list agencies before retrying because the endpoint does not declare an idempotency key.\n\n### Error notes\n- 400 can indicate missing `name`, missing `commissionRate`, invalid email, commission rate outside 0 through 100, invalid contract dates, or a start date on/after the end date.\n- 403 means the caller lacks Collections write access.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Required human-readable agency name. Keep it operational rather than patient-specific."},"contactName":{"type":"string","minLength":1,"maxLength":160,"description":"Name of the payer, patient, agency, or internal contact reached during follow-up."},"contactEmail":{"type":"string","maxLength":254,"format":"email","description":"Optional agency email address. Do not use it to store credentials or tokens."},"contactPhone":{"type":"string","minLength":1,"maxLength":40},"address":{"type":"string","minLength":1,"maxLength":500,"description":"Street address for the patient, subscriber, provider, or recipient context. Treat address values as PHI when tied to a person."},"commissionRate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Required agency commission percentage from 0 through 100."},"contractStartDate":{"type":"string","minLength":1,"description":"Optional contract start date string. Runtime create behavior rejects invalid dates and date ranges where the start is not before the end."},"contractEndDate":{"type":"string","minLength":1,"description":"Optional contract end date string. Runtime create behavior rejects invalid dates and date ranges where the end is not after the start."}},"required":["name","commissionRate"]},"example":{"name":"Example collection_agency","commissionRate":1.25,"contactName":"Example collection_agency","contactEmail":"developer@example.com","contactPhone":"+15551234567","address":"example-address","contractStartDate":"2026-06-08","contractEndDate":"2026-06-08"}}},"description":"`name` and `commissionRate` are required. `commissionRate` is a number from 0 through 100. Contact fields and address are optional. `contractStartDate` and `contractEndDate` are optional non-empty strings in the OpenAPI schema, and the runtime create path rejects invalid date strings and rejects a start date that is on or after the end date when both are supplied."},"responses":{"201":{"description":"Collection agency created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"contactName":{"type":["string","null"]},"contactEmail":{"type":["string","null"]},"contactPhone":{"type":["string","null"]},"address":{"type":["string","null"]},"status":{"type":"string","enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]},"commissionRate":{"type":"string"},"contractStartDate":{"type":["string","null"],"format":"date-time"},"contractEndDate":{"type":["string","null"],"format":"date-time"},"totalPlaced":{"type":"integer"},"totalRecovered":{"type":"string"},"recoveryRate":{"type":"string"},"avgDaysToRecover":{"type":["integer","null"]},"recentPlacements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"}},"required":["id","status","totalBalance","recoveredAmount"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","contactName","contactEmail","contactPhone","address","status","commissionRate","contractStartDate","contractEndDate","totalPlaced","totalRecovered","recoveryRate","avgDaysToRecover","recentPlacements","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example collection_agency","contactName":"Example collection_agency","contactEmail":"developer@example.com","contactPhone":"+15551234567","address":"example-address","status":"CA_ACTIVE","commissionRate":"example-commissionrate","contractStartDate":"2026-06-08T10:15:30Z","contractEndDate":"2026-06-08T10:15:30Z","totalPlaced":1,"totalRecovered":"example-totalrecovered","recoveryRate":"example-recoveryrate","avgDaysToRecover":1,"recentPlacements":[{"id":"00000000-0000-4000-8000-000000000001","status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount"}],"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/agencies/{agencyId}":{"get":{"operationId":"getCollectionAgency","summary":"Get collection agency","description":"Returns one collection agency when `agencyId` resolves inside the authenticated organization.\n\n### When to use\nUse this after listCollectionAgencies or a create/update response gives you an agency id and you need current agency configuration or recent placement rollups.\n\n### Before calling\nUse an `agencyId` obtained from the same API-key organization context. Authenticate with Collections read or write access.\n\n### Request guidance\nPass `agencyId` in the path. Do not include tenant selectors, agency portal credentials, or unrelated placement data in the request.\n\n### Request notes\n- `agencyId` is a path parameter and must be non-empty.\n- Wrong-tenant ids should be documented as not found or forbidden-style outcomes, not as cross-tenant visibility.\n\n### Response semantics\nThe response contains one local agency record with contact fields, commission/rate metrics, contract dates, and recent placement rollups. It is not an external agency status check.\n\n### Response notes\n- `organizationId` in the response is the authenticated organization.\n- `recentPlacements` is a local rollup, not a full placement history.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization agency context unless a prior trusted response proves the agency should exist. Retry only transient 5xx or 429 responses.\n\n### Error notes\n- 404 means the agency was not found in the authenticated organization.\n- 401 and 403 require credential, scope, or tenant-context correction.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agencyId","in":"path","description":"QuickRCM collection agency identifier from the path. It must belong to the organization selected by the bearer API key."}],"responses":{"200":{"description":"Collection agency","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"contactName":{"type":["string","null"]},"contactEmail":{"type":["string","null"]},"contactPhone":{"type":["string","null"]},"address":{"type":["string","null"]},"status":{"type":"string","enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]},"commissionRate":{"type":"string"},"contractStartDate":{"type":["string","null"],"format":"date-time"},"contractEndDate":{"type":["string","null"],"format":"date-time"},"totalPlaced":{"type":"integer"},"totalRecovered":{"type":"string"},"recoveryRate":{"type":"string"},"avgDaysToRecover":{"type":["integer","null"]},"recentPlacements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"}},"required":["id","status","totalBalance","recoveredAmount"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","contactName","contactEmail","contactPhone","address","status","commissionRate","contractStartDate","contractEndDate","totalPlaced","totalRecovered","recoveryRate","avgDaysToRecover","recentPlacements","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example collection_agency","contactName":"Example collection_agency","contactEmail":"developer@example.com","contactPhone":"+15551234567","address":"example-address","status":"CA_ACTIVE","commissionRate":"example-commissionrate","contractStartDate":"2026-06-08T10:15:30Z","contractEndDate":"2026-06-08T10:15:30Z","totalPlaced":1,"totalRecovered":"example-totalrecovered","recoveryRate":"example-recoveryrate","avgDaysToRecover":1,"recentPlacements":[{"id":"00000000-0000-4000-8000-000000000001","status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount"}],"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Collection agency not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"updateCollectionAgency","summary":"Update collection agency","description":"Updates editable fields on an organization-owned collection agency.\n\n### When to use\nUse this when agency contact details, commission rate, contract date metadata, or agency status changes in local QuickRCM configuration.\n\n### Before calling\nAuthenticate with `collections:write`, load the current agency, and confirm downstream workflows can tolerate any status or commission-rate change.\n\n### Request guidance\nAll body fields are optional. `status` must be one of the collection agency status enum values. `commissionRate` must be 0 through 100. Supplied contract dates must parse as dates; when both contract dates are supplied, `contractStartDate` must be before `contractEndDate`.\n\n### Request notes\n- `agencyId` selects the agency in the path.\n- Use `CA_SUSPENDED` or other status values only according to organization policy.\n- Do not use agency notes or contact fields to store patient-level facts.\n\n### Response semantics\nThe response returns the updated local agency record. Existing placements are not automatically transmitted, recalled, or recalculated by this endpoint's public contract.\n\n### Response notes\n- The response is local agency state after update.\n- Agency status changes do not imply external agency notification.\n\n### Errors and retries\nTreat 400 as invalid editable fields or invalid contract date logic. Treat 404 as missing or wrong-organization agency context. Re-read after timeouts before retrying to avoid overwriting newer admin changes.\n\n### Error notes\n- 400 can indicate invalid date strings or contract start date on/after end date.\n- 404 can hide wrong-tenant agency identifiers.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"agencyId","in":"path","description":"QuickRCM collection agency identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Human-readable name for the queue, template, person, payer, or workflow object."},"contactName":{"type":"string","minLength":1,"maxLength":160,"description":"Name of the payer, patient, agency, or internal contact reached during follow-up."},"contactEmail":{"type":"string","maxLength":254,"format":"email"},"contactPhone":{"type":"string","minLength":1,"maxLength":40},"address":{"type":"string","minLength":1,"maxLength":500,"description":"Street address for the patient, subscriber, provider, or recipient context. Treat address values as PHI when tied to a person."},"commissionRate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Agency commission percentage from 0 through 100. Preserve decimal precision and do not confuse it with an amount."},"contractStartDate":{"type":"string","minLength":1,"description":"Optional contract start date string. When paired with `contractEndDate`, it must parse before the end date."},"contractEndDate":{"type":"string","minLength":1,"description":"Optional contract end date string. When paired with `contractStartDate`, it must parse after the start date."},"status":{"type":"string","enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"],"description":"Updated local agency status. Valid values are `CA_ACTIVE`, `CA_INACTIVE`, `CA_SUSPENDED`, and `CA_TERMINATED`."}}},"example":{"name":"Example collection_agency","contactName":"Example collection_agency","contactEmail":"developer@example.com","contactPhone":"+15551234567","address":"example-address","commissionRate":1.25,"contractStartDate":"2026-06-08","contractEndDate":"2026-06-08"}}},"description":"All body fields are optional. `status` must be one of the collection agency status enum values. `commissionRate` must be 0 through 100. Supplied contract dates must parse as dates; when both contract dates are supplied, `contractStartDate` must be before `contractEndDate`."},"responses":{"200":{"description":"Updated collection agency","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"contactName":{"type":["string","null"]},"contactEmail":{"type":["string","null"]},"contactPhone":{"type":["string","null"]},"address":{"type":["string","null"]},"status":{"type":"string","enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]},"commissionRate":{"type":"string"},"contractStartDate":{"type":["string","null"],"format":"date-time"},"contractEndDate":{"type":["string","null"],"format":"date-time"},"totalPlaced":{"type":"integer"},"totalRecovered":{"type":"string"},"recoveryRate":{"type":"string"},"avgDaysToRecover":{"type":["integer","null"]},"recentPlacements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"}},"required":["id","status","totalBalance","recoveredAmount"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","contactName","contactEmail","contactPhone","address","status","commissionRate","contractStartDate","contractEndDate","totalPlaced","totalRecovered","recoveryRate","avgDaysToRecover","recentPlacements","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example collection_agency","contactName":"Example collection_agency","contactEmail":"developer@example.com","contactPhone":"+15551234567","address":"example-address","status":"CA_ACTIVE","commissionRate":"example-commissionrate","contractStartDate":"2026-06-08T10:15:30Z","contractEndDate":"2026-06-08T10:15:30Z","totalPlaced":1,"totalRecovered":"example-totalrecovered","recoveryRate":"example-recoveryrate","avgDaysToRecover":1,"recentPlacements":[{"id":"00000000-0000-4000-8000-000000000001","status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount"}],"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Collection agency not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/placements":{"get":{"operationId":"listBadDebtPlacements","summary":"List bad debt placements","description":"Lists bad debt placement records owned by the authenticated organization, with optional status, agency, patient, and skip/take filters.\n\n### When to use\nUse this to build collections worklists, reconcile placement state, monitor recalled or working placements, or find placement ids before recovery, recall, dispute, or validation-notice workflows.\n\n### Before calling\nAuthenticate with Collections read or write access. Use the narrowest status, agency, or patient filter available and bounded pagination.\n\n### Request guidance\n`status` must be a placement lifecycle enum value. `agencyId` and `patientId` are optional filters. `skip` defaults to 0; `take` defaults to 25 and is capped at 100. Treat `patientId` as patient-identifying in logs and analytics.\n\n### Request notes\n- Use `agencyId` from listCollectionAgencies or getCollectionAgency in the same tenant.\n- `patientId` is patient-identifying; avoid logging raw filter values.\n- No free-text search parameter is declared for this endpoint.\n\n### Response semantics\nThe response returns `data.placements`, `total`, `skip`, and `take`. Each placement includes local balance/recovery strings, status, patient/account/claim identifiers, optional statute fields, optional agency summary, and local timestamps.\n\n### Response notes\n- `totalBalance`, `recoveredAmount`, `commissionAmount`, and `propensityScore` are serialized as strings or null.\n- `agency` is a limited nested summary.\n- Placement rows are local QuickRCM records; external collection agency state is not guaranteed.\n\n### Errors and retries\nCorrect invalid enum or pagination values before retrying. Retry 429 with backoff. Treat returned placement data as local workflow state, not agency acknowledgment.\n\n### Error notes\n- 400 can indicate invalid placement status or pagination values.\n- 403 means insufficient Collections scope.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"required":false,"name":"status","in":"query","description":"Optional placement status filter. Valid values are `PL_PENDING`, `PL_SENT`, `PL_ACKNOWLEDGED`, `PL_WORKING`, `PL_RECALLED`, `PL_PAID_IN_FULL`, `PL_SETTLED`, `PL_RETURNED`, and `PL_STATUTE_EXPIRED`."},{"schema":{"type":"string","minLength":1},"required":false,"name":"agencyId","in":"query","description":"Optional filter for placements assigned to one collection agency in the authenticated organization."},{"schema":{"type":"string","minLength":1},"required":false,"name":"patientId","in":"query","description":"Optional QuickRCM patient identifier filter. Treat as patient-identifying and avoid logging raw values."},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"skip","in":"query","description":"Number of records to skip for pagination. Use with take when the endpoint exposes skip/take pagination."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"take","in":"query","description":"Maximum number of records to take for skip/take pagination."}],"responses":{"200":{"description":"Bad debt placements for the authenticated organization","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"placements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agencyId":{"type":"string"},"patientId":{"type":"string"},"patientAccountId":{"type":["string","null"]},"claimIds":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"},"commissionAmount":{"type":"string"},"propensityScore":{"type":["string","null"]},"debtAgeDays":{"type":["integer","null"]},"placementDate":{"type":["string","null"],"format":"date-time"},"recallDate":{"type":["string","null"],"format":"date-time"},"recallReason":{"type":["string","null"]},"statuteOfLimitationsDate":{"type":["string","null"],"format":"date-time"},"statuteState":{"type":["string","null"]},"agency":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"],"enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]}},"required":["id","name","status"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agencyId","patientId","patientAccountId","claimIds","status","totalBalance","recoveredAmount","commissionAmount","propensityScore","debtAgeDays","placementDate","recallDate","recallReason","statuteOfLimitationsDate","statuteState","agency","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["placements","total","skip","take"]}},"required":["success","data"]},"example":{"success":true,"data":{"placements":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agencyId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","patientAccountId":"00000000-0000-4000-8000-000000000001","claimIds":["example-claimids"],"status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount","commissionAmount":"example-commissionamount","propensityScore":"example-propensityscore","debtAgeDays":1,"placementDate":"2026-06-08T10:15:30Z","recallDate":"2026-06-08T10:15:30Z","recallReason":"example-recallreason","statuteOfLimitationsDate":"2026-06-08T10:15:30Z","statuteState":"example-statutestate","agency":{"id":"00000000-0000-4000-8000-000000000001","name":"Example bad_debt_placement","status":"CA_ACTIVE"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"skip":1,"take":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createBadDebtPlacements","summary":"Create bad debt placements","description":"Creates one or more local bad debt placement records after validating that the target agency is active in the authenticated organization.\n\n### When to use\nUse this when an integration or workflow has selected accounts to move into QuickRCM collections tracking under a configured active agency.\n\n### Before calling\nAuthenticate with `collections:write`. Resolve `agencyId` from an active agency in the same tenant. Build an `accounts` array with 1 through 100 entries and include only identifiers and balances needed for placement tracking.\n\n### Request guidance\n`agencyId` and `accounts` are required. Each account requires `patientId` and positive `totalBalance`; optional fields include `patientAccountId`, `claimIds`, `debtAgeDays`, `statuteState`, and `debtOriginDate`. If `statuteState` is supplied, provide a parseable `debtOriginDate` so statute metadata can be calculated. Use same-tenant patient/account/claim identifiers, but document this as caller responsibility rather than full public referential validation for every supplied id.\n\n### Request notes\n- `accounts` must contain at least 1 and at most 100 entries.\n- `totalBalance` must be a positive number.\n- Use same-tenant `patientId`, `patientAccountId`, and `claimIds`; the handler stores these as local references.\n- Do not send raw statements, raw Electronic Data Interchange (EDI), transcripts, portal payloads, payment credentials, or unnecessary demographics.\n\n### Response semantics\nA 201 response returns created local placement records, `count`, and a `skipped` array for account entries that could not be placed. Created placements are local records with status `PL_PENDING`; when at least one placement is created, the active agency's local `totalPlaced` count is incremented. This endpoint does not transmit debt packages to an external agency.\n\n### Response notes\n- Created placement status is local placement workflow state.\n- `skipped` entries include patientId and reason for account-level failures.\n- This endpoint is local record creation, not external agency submission.\n\n### Errors and retries\nA 404 means the target active agency was not found in the authenticated organization. A 400 can occur when validation fails or all account entries are invalid. After a timeout, list placements before retrying because the endpoint does not declare idempotent replay behavior.\n\n### Error notes\n- 404 means no active agency matched `agencyId` for the API key organization.\n- 400 can indicate all accounts were invalid, missing required fields, invalid balances, missing debt origin date for statute metadata, or invalid debt origin date.\n- Retry carefully after network failures to avoid duplicate local placements.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agencyId":{"type":"string","minLength":1,"description":"Required active collection agency identifier in the authenticated organization."},"accounts":{"type":"array","items":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"QuickRCM patient identifier. The patient must belong to the organization selected by the bearer API key."},"patientAccountId":{"type":"string","minLength":1,"description":"Optional QuickRCM patient AR account identifier supplied by the caller as a local reference."},"claimIds":{"type":"array","items":{"type":"string","minLength":1},"default":[],"description":"Optional array of QuickRCM claim identifiers supplied by the caller as local references."},"totalBalance":{"type":"number","exclusiveMinimum":0,"description":"Required positive balance amount to place into local collections tracking."},"debtAgeDays":{"type":["integer","null"],"minimum":0,"description":"Optional whole number of days the debt has aged."},"statuteState":{"type":"string","minLength":2,"maxLength":2,"description":"Optional two-character state used for statute-of-limitations metadata."},"debtOriginDate":{"type":"string","minLength":1,"description":"Optional origin date string. Required by current behavior when `statuteState` is supplied."}},"required":["patientId","totalBalance"]},"minItems":1,"maxItems":100,"description":"Required array of 1 through 100 account placement inputs."}},"required":["agencyId","accounts"]},"example":{"agencyId":"00000000-0000-4000-8000-000000000001","accounts":[{"patientId":"00000000-0000-4000-8000-000000000001","totalBalance":1,"patientAccountId":"00000000-0000-4000-8000-000000000001","claimIds":[],"debtAgeDays":1,"statuteState":"example-statutestate","debtOriginDate":"2026-06-08"}]}}},"description":"`agencyId` and `accounts` are required. Each account requires `patientId` and positive `totalBalance`; optional fields include `patientAccountId`, `claimIds`, `debtAgeDays`, `statuteState`, and `debtOriginDate`. If `statuteState` is supplied, provide a parseable `debtOriginDate` so statute metadata can be calculated. Use same-tenant patient/account/claim identifiers, but document this as caller responsibility rather than full public referential validation for every supplied id."},"responses":{"201":{"description":"Bad debt placements created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"placements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agencyId":{"type":"string"},"patientId":{"type":"string"},"patientAccountId":{"type":["string","null"]},"claimIds":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"},"commissionAmount":{"type":"string"},"propensityScore":{"type":["string","null"]},"debtAgeDays":{"type":["integer","null"]},"placementDate":{"type":["string","null"],"format":"date-time"},"recallDate":{"type":["string","null"],"format":"date-time"},"recallReason":{"type":["string","null"]},"statuteOfLimitationsDate":{"type":["string","null"],"format":"date-time"},"statuteState":{"type":["string","null"]},"agency":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"],"enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]}},"required":["id","name","status"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agencyId","patientId","patientAccountId","claimIds","status","totalBalance","recoveredAmount","commissionAmount","propensityScore","debtAgeDays","placementDate","recallDate","recallReason","statuteOfLimitationsDate","statuteState","agency","createdAt","updatedAt"]}},"count":{"type":"integer","minimum":0},"skipped":{"type":"array","items":{"type":"object","properties":{"patientId":{"type":"string"},"reason":{"type":"string"}},"required":["patientId","reason"]}}},"required":["placements","count","skipped"]}},"required":["success","data"]},"example":{"success":true,"data":{"placements":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agencyId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","patientAccountId":"00000000-0000-4000-8000-000000000001","claimIds":["example-claimids"],"status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount","commissionAmount":"example-commissionamount","propensityScore":"example-propensityscore","debtAgeDays":1,"placementDate":"2026-06-08T10:15:30Z","recallDate":"2026-06-08T10:15:30Z","recallReason":"example-recallreason","statuteOfLimitationsDate":"2026-06-08T10:15:30Z","statuteState":"example-statutestate","agency":{"id":"00000000-0000-4000-8000-000000000001","name":"Example bad_debt_placement","status":"CA_ACTIVE"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"count":1,"skipped":[{"patientId":"00000000-0000-4000-8000-000000000001","reason":"example-reason"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Active collection agency not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/placements/{placementId}":{"get":{"operationId":"getBadDebtPlacement","summary":"Get bad debt placement","description":"Returns one bad debt placement when `placementId` belongs to the authenticated organization.\n\n### When to use\nUse this after listBadDebtPlacements, createBadDebtPlacements, or another trusted QuickRCM response gives you a placement id.\n\n### Before calling\nAuthenticate with Collections read or write access and use a placement id obtained in the same tenant context.\n\n### Request guidance\nPass `placementId` in the path. Do not include organization selectors or external agency credentials in the request.\n\n### Request notes\n- `placementId` must be non-empty.\n- Do not guess placement ids across tenants.\n\n### Response semantics\nThe response returns one local bad debt placement with balance/recovery strings, status, patient/account/claim identifiers, optional statute metadata, optional agency summary, and timestamps.\n\n### Response notes\n- The returned placement is local QuickRCM workflow state.\n- The response does not include agency portal payloads or payment credentials.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization placement context. Retry only transient 5xx or 429 responses.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant placement identifiers.\n- 401 and 403 require credential or scope correction.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"placementId","in":"path","description":"QuickRCM bad debt placement identifier from the path. It must belong to the API key organization."}],"responses":{"200":{"description":"Bad debt placement","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agencyId":{"type":"string"},"patientId":{"type":"string"},"patientAccountId":{"type":["string","null"]},"claimIds":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"},"commissionAmount":{"type":"string"},"propensityScore":{"type":["string","null"]},"debtAgeDays":{"type":["integer","null"]},"placementDate":{"type":["string","null"],"format":"date-time"},"recallDate":{"type":["string","null"],"format":"date-time"},"recallReason":{"type":["string","null"]},"statuteOfLimitationsDate":{"type":["string","null"],"format":"date-time"},"statuteState":{"type":["string","null"]},"agency":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"],"enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]}},"required":["id","name","status"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agencyId","patientId","patientAccountId","claimIds","status","totalBalance","recoveredAmount","commissionAmount","propensityScore","debtAgeDays","placementDate","recallDate","recallReason","statuteOfLimitationsDate","statuteState","agency","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agencyId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","patientAccountId":"00000000-0000-4000-8000-000000000001","claimIds":["example-claimids"],"status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount","commissionAmount":"example-commissionamount","propensityScore":"example-propensityscore","debtAgeDays":1,"placementDate":"2026-06-08T10:15:30Z","recallDate":"2026-06-08T10:15:30Z","recallReason":"example-recallreason","statuteOfLimitationsDate":"2026-06-08T10:15:30Z","statuteState":"example-statutestate","agency":{"id":"00000000-0000-4000-8000-000000000001","name":"Example bad_debt_placement","status":"CA_ACTIVE"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Bad debt placement not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/placements/{placementId}/recovery":{"put":{"operationId":"recordBadDebtRecovery","summary":"Record bad debt recovery","description":"Records a positive local recovery amount against an organization-owned bad debt placement that is in a recoverable agency-work status.\n\n### When to use\nUse this after staff or an integration has verified a recovery event that should update QuickRCM collections tracking.\n\n### Before calling\nAuthenticate with `collections:write`, resolve `placementId` from the same tenant, and confirm the recovered amount is already verified by the source workflow. The placement must be in `PL_SENT`, `PL_ACKNOWLEDGED`, or `PL_WORKING`.\n\n### Request guidance\n`recoveredAmount` is required and must be positive. `notes` is optional and capped at 1000 characters. `settlementAccepted` is optional settlement context. The endpoint rejects recoveries that would push total recovered over the balance plus the documented 1 percent rounding tolerance used by the handler.\n\n### Request notes\n- `recoveredAmount` must be greater than 0.\n- Allowed source statuses are `PL_SENT`, `PL_ACKNOWLEDGED`, and `PL_WORKING`.\n- Keep `notes` sanitized and free of payer credentials, full payment details, card numbers, and unnecessary Protected Health Information (PHI).\n- `settlementAccepted` indicates local settlement context; it is not payment processing.\n\n### Response semantics\nThe response returns the updated local placement. On success the handler increments placement `recoveredAmount`, increments placement `commissionAmount` from the agency commission rate, increments agency `totalRecovered`, and appends a sanitized local recovery note. The placement status can move to `PL_PAID_IN_FULL` when recovered totals reach at least 99 percent of balance, or to `PL_SETTLED` when `settlementAccepted` is true and the paid-in-full threshold is not met. This endpoint does not collect money, charge a card, post a payment, or prove agency remittance.\n\n### Response notes\n- Returned balances are local placement fields serialized as strings.\n- Successful recovery updates agency totals in addition to the placement.\n- The response is not a payment receipt.\n\n### Errors and retries\nFix invalid amounts, over-recovery, non-recoverable status, or note length before retrying. Treat 404 as missing or wrong-organization placement context. After timeouts, re-read the placement before retrying to avoid duplicate recovery increments.\n\n### Error notes\n- 400 can indicate non-positive recovery amount, note length over 1000 characters, non-recoverable placement status, or over-recovery above the tolerance.\n- 404 can indicate the placement id does not belong to the authenticated organization.\n- Do not blindly retry after a timeout because the endpoint increments amounts.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"placementId","in":"path","description":"QuickRCM bad debt placement identifier. Placement read/write handlers look it up inside the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recoveredAmount":{"type":"number","exclusiveMinimum":0,"description":"Required positive amount to add to local placement recovery totals."},"notes":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional sanitized local note appended to recovery audit text; capped at 1000 characters."},"settlementAccepted":{"type":"boolean","description":"Optional flag that can move the local placement to `PL_SETTLED` unless recovered totals meet the paid-in-full threshold."}},"required":["recoveredAmount"]},"example":{"recoveredAmount":125.5,"notes":"Example bad_debt_recovery note","settlementAccepted":true}}},"description":"`recoveredAmount` is required and must be positive. `notes` is optional and capped at 1000 characters. `settlementAccepted` is optional settlement context. The endpoint rejects recoveries that would push total recovered over the balance plus the documented 1 percent rounding tolerance used by the handler."},"responses":{"200":{"description":"Updated bad debt placement","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agencyId":{"type":"string"},"patientId":{"type":"string"},"patientAccountId":{"type":["string","null"]},"claimIds":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"},"commissionAmount":{"type":"string"},"propensityScore":{"type":["string","null"]},"debtAgeDays":{"type":["integer","null"]},"placementDate":{"type":["string","null"],"format":"date-time"},"recallDate":{"type":["string","null"],"format":"date-time"},"recallReason":{"type":["string","null"]},"statuteOfLimitationsDate":{"type":["string","null"],"format":"date-time"},"statuteState":{"type":["string","null"]},"agency":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"],"enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]}},"required":["id","name","status"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agencyId","patientId","patientAccountId","claimIds","status","totalBalance","recoveredAmount","commissionAmount","propensityScore","debtAgeDays","placementDate","recallDate","recallReason","statuteOfLimitationsDate","statuteState","agency","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agencyId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","patientAccountId":"00000000-0000-4000-8000-000000000001","claimIds":["example-claimids"],"status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount","commissionAmount":"example-commissionamount","propensityScore":"example-propensityscore","debtAgeDays":1,"placementDate":"2026-06-08T10:15:30Z","recallDate":"2026-06-08T10:15:30Z","recallReason":"example-recallreason","statuteOfLimitationsDate":"2026-06-08T10:15:30Z","statuteState":"example-statutestate","agency":{"id":"00000000-0000-4000-8000-000000000001","name":"Example bad_debt_recovery","status":"CA_ACTIVE"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Bad debt placement not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/placements/{placementId}/recall":{"post":{"operationId":"recallBadDebtPlacement","summary":"Recall bad debt placement","description":"Marks an organization-owned bad debt placement as recalled in local QuickRCM collections tracking when its current status is recallable.\n\n### When to use\nUse this when an account should stop active agency-work tracking because of direct resolution, placement error, policy decision, dispute handling, or other operational recall reason.\n\n### Before calling\nAuthenticate with `collections:write`, retrieve the placement, and confirm its current status is one of `PL_PENDING`, `PL_SENT`, `PL_ACKNOWLEDGED`, or `PL_WORKING`.\n\n### Request guidance\n`recallReason` is required, trimmed, sanitized, and capped at 1000 characters. Avoid Protected Health Information (PHI), credentials, or payment details in recall text.\n\n### Request notes\n- `recallReason` is required.\n- Recallable statuses are `PL_PENDING`, `PL_SENT`, `PL_ACKNOWLEDGED`, and `PL_WORKING`.\n- This endpoint records local recall state only.\n\n### Response semantics\nThe response returns the updated local placement. On success the handler sets status to `PL_RECALLED`, stores `recallDate`, stores sanitized `recallReason`, and decrements the agency's local `totalPlaced` count. It does not notify an external collection agency by itself.\n\n### Response notes\n- `status` becomes `PL_RECALLED` on success.\n- `recallDate` is set by the server.\n- Agency `totalPlaced` is decremented as a local aggregate side effect.\n\n### Errors and retries\nTreat 400 as missing reason or non-recallable placement status. Treat 404 as missing or wrong-organization placement context. After a timeout, re-read before retrying because a successful recall mutates placement and agency counters.\n\n### Error notes\n- 400 can indicate an invalid status transition.\n- 404 can hide wrong-tenant placement identifiers.\n- Retry only after checking the current placement state.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"placementId","in":"path","description":"QuickRCM bad debt placement identifier. Placement read/write handlers look it up inside the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recallReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Required local reason for recalling a placement, sanitized before storage and capped at 1000 characters."}},"required":["recallReason"]},"example":{"recallReason":"example-recallreason"}}},"description":"`recallReason` is required, trimmed, sanitized, and capped at 1000 characters. Avoid Protected Health Information (PHI), credentials, or payment details in recall text."},"responses":{"200":{"description":"Recalled bad debt placement","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agencyId":{"type":"string"},"patientId":{"type":"string"},"patientAccountId":{"type":["string","null"]},"claimIds":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"},"commissionAmount":{"type":"string"},"propensityScore":{"type":["string","null"]},"debtAgeDays":{"type":["integer","null"]},"placementDate":{"type":["string","null"],"format":"date-time"},"recallDate":{"type":["string","null"],"format":"date-time"},"recallReason":{"type":["string","null"]},"statuteOfLimitationsDate":{"type":["string","null"],"format":"date-time"},"statuteState":{"type":["string","null"]},"agency":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"],"enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]}},"required":["id","name","status"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agencyId","patientId","patientAccountId","claimIds","status","totalBalance","recoveredAmount","commissionAmount","propensityScore","debtAgeDays","placementDate","recallDate","recallReason","statuteOfLimitationsDate","statuteState","agency","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agencyId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","patientAccountId":"00000000-0000-4000-8000-000000000001","claimIds":["example-claimids"],"status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount","commissionAmount":"example-commissionamount","propensityScore":"example-propensityscore","debtAgeDays":1,"placementDate":"2026-06-08T10:15:30Z","recallDate":"2026-06-08T10:15:30Z","recallReason":"example-recallreason","statuteOfLimitationsDate":"2026-06-08T10:15:30Z","statuteState":"example-statutestate","agency":{"id":"00000000-0000-4000-8000-000000000001","name":"Example bad_debt_placement","status":"CA_ACTIVE"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Bad debt placement not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/placements/{placementId}/disputes":{"post":{"operationId":"recordPlacementDispute","summary":"Record placement dispute","description":"Appends a local dispute note to an organization-owned bad debt placement.\n\n### When to use\nUse this when staff or an integration has received dispute context that should be retained on the local placement record.\n\n### Before calling\nAuthenticate with `collections:write` and retrieve the placement from the same organization. Decide whether a short sanitized `disputeReason` is necessary.\n\n### Request guidance\n`disputeReason` is optional and capped at 1000 characters. The public handler updates local placement notes; it does not create a separate dispute resource, transmit to an agency, or modify payer state.\n\n### Request notes\n- Keep `disputeReason` concise and sanitized.\n- Do not include raw statements, transcripts, legal filings, or unnecessary Protected Health Information (PHI).\n- No `disputeId` is returned by this endpoint.\n\n### Response semantics\nThe response returns the updated placement after a timestamped `DISPUTE FILED` note is appended. It does not return a standalone dispute object, and the current public handler does not document a `disputedFlag` state transition.\n\n### Response notes\n- The returned object is the updated placement.\n- The public API records local note evidence only.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization placement. Re-read after timeouts before retrying because the endpoint appends notes.\n\n### Error notes\n- 400 can indicate invalid note length.\n- 404 can indicate the placement is absent or not visible to the API key organization.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"placementId","in":"path","description":"QuickRCM bad debt placement identifier. Placement read/write handlers look it up inside the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"disputeReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional local reason for recording a placement dispute; sanitized and appended to notes."}}},"example":{"disputeReason":"example-disputereason"}}},"description":"`disputeReason` is optional and capped at 1000 characters. The public handler updates local placement notes; it does not create a separate dispute resource, transmit to an agency, or modify payer state."},"responses":{"200":{"description":"Updated bad debt placement","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agencyId":{"type":"string"},"patientId":{"type":"string"},"patientAccountId":{"type":["string","null"]},"claimIds":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"},"commissionAmount":{"type":"string"},"propensityScore":{"type":["string","null"]},"debtAgeDays":{"type":["integer","null"]},"placementDate":{"type":["string","null"],"format":"date-time"},"recallDate":{"type":["string","null"],"format":"date-time"},"recallReason":{"type":["string","null"]},"statuteOfLimitationsDate":{"type":["string","null"],"format":"date-time"},"statuteState":{"type":["string","null"]},"agency":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"],"enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]}},"required":["id","name","status"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agencyId","patientId","patientAccountId","claimIds","status","totalBalance","recoveredAmount","commissionAmount","propensityScore","debtAgeDays","placementDate","recallDate","recallReason","statuteOfLimitationsDate","statuteState","agency","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agencyId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","patientAccountId":"00000000-0000-4000-8000-000000000001","claimIds":["example-claimids"],"status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount","commissionAmount":"example-commissionamount","propensityScore":"example-propensityscore","debtAgeDays":1,"placementDate":"2026-06-08T10:15:30Z","recallDate":"2026-06-08T10:15:30Z","recallReason":"example-recallreason","statuteOfLimitationsDate":"2026-06-08T10:15:30Z","statuteState":"example-statutestate","agency":{"id":"00000000-0000-4000-8000-000000000001","name":"Example placement_dispute","status":"CA_ACTIVE"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Bad debt placement not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/placements/{placementId}/disputes/{disputeId}/resolve":{"put":{"operationId":"resolvePlacementDispute","summary":"Resolve placement dispute","description":"Appends a local dispute resolution note to an organization-owned placement and can replace the local total balance with a verified amount.\n\n### When to use\nUse this after a dispute has been reviewed and QuickRCM should retain a local resolution note or verified balance.\n\n### Before calling\nAuthenticate with `collections:write`, retrieve the placement, and prepare a concise resolution. Include `verifiedAmount` only when a verified positive balance should replace local balance metadata.\n\n### Request guidance\n`resolution` is required and capped at 1000 characters. `verifiedAmount` is optional and must be positive. `disputeId` is required in the path but the current public response remains the updated placement rather than a separate dispute resource.\n\n### Request notes\n- `resolution` is required.\n- `verifiedAmount` replaces local `totalBalance` when supplied.\n- Do not use this endpoint as proof that an agency, payer, or patient accepted the resolution.\n\n### Response semantics\nThe response returns the updated placement after a timestamped `DISPUTE RESOLVED` note is appended and optional `totalBalance` is replaced. The public handler evidence does not show a standalone dispute lifecycle object.\n\n### Response notes\n- The response is the updated placement.\n- No separate dispute object is returned.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization placement. Re-read after timeouts before retrying because this endpoint appends notes and may change totalBalance.\n\n### Error notes\n- 400 can indicate missing resolution or invalid verified amount.\n- 404 can indicate missing or wrong-tenant placement context.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"placementId","in":"path","description":"QuickRCM bad debt placement identifier. Placement read/write handlers look it up inside the organization selected by the bearer API key."},{"schema":{"type":"string","minLength":1},"required":true,"name":"disputeId","in":"path","description":"Path identifier on the dispute resolution route. The current public response remains the updated placement rather than a separate dispute resource."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string","minLength":1,"maxLength":1000,"description":"Required sanitized local resolution text capped at 1000 characters."},"verifiedAmount":{"type":"number","exclusiveMinimum":0,"description":"Optional positive amount recorded as locally verified during dispute resolution."}},"required":["resolution"]},"example":{"resolution":"example-resolution","verifiedAmount":125.5}}},"description":"`resolution` is required and capped at 1000 characters. `verifiedAmount` is optional and must be positive. `disputeId` is required in the path but the current public response remains the updated placement rather than a separate dispute resource."},"responses":{"200":{"description":"Updated bad debt placement","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"agencyId":{"type":"string"},"patientId":{"type":"string"},"patientAccountId":{"type":["string","null"]},"claimIds":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PL_PENDING","PL_SENT","PL_ACKNOWLEDGED","PL_WORKING","PL_RECALLED","PL_PAID_IN_FULL","PL_SETTLED","PL_RETURNED","PL_STATUTE_EXPIRED"]},"totalBalance":{"type":"string"},"recoveredAmount":{"type":"string"},"commissionAmount":{"type":"string"},"propensityScore":{"type":["string","null"]},"debtAgeDays":{"type":["integer","null"]},"placementDate":{"type":["string","null"],"format":"date-time"},"recallDate":{"type":["string","null"],"format":"date-time"},"recallReason":{"type":["string","null"]},"statuteOfLimitationsDate":{"type":["string","null"],"format":"date-time"},"statuteState":{"type":["string","null"]},"agency":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":["string","null"],"enum":["CA_ACTIVE","CA_INACTIVE","CA_SUSPENDED","CA_TERMINATED"]}},"required":["id","name","status"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","agencyId","patientId","patientAccountId","claimIds","status","totalBalance","recoveredAmount","commissionAmount","propensityScore","debtAgeDays","placementDate","recallDate","recallReason","statuteOfLimitationsDate","statuteState","agency","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","agencyId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","patientAccountId":"00000000-0000-4000-8000-000000000001","claimIds":["example-claimids"],"status":"PL_PENDING","totalBalance":"example-totalbalance","recoveredAmount":"example-recoveredamount","commissionAmount":"example-commissionamount","propensityScore":"example-propensityscore","debtAgeDays":1,"placementDate":"2026-06-08T10:15:30Z","recallDate":"2026-06-08T10:15:30Z","recallReason":"example-recallreason","statuteOfLimitationsDate":"2026-06-08T10:15:30Z","statuteState":"example-statutestate","agency":{"id":"00000000-0000-4000-8000-000000000001","name":"Example placement_dispute","status":"CA_ACTIVE"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Bad debt placement not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/placements/{placementId}/validation-notice":{"post":{"operationId":"sendDebtValidationNotice","summary":"Validate or queue debt validation notice","description":"Validates or queues local debt validation notice evidence for an organization-owned placement without external delivery.\n\n### When to use\nUse this when an integration needs a safe simulation or local queue marker before any regulated debt validation communication workflow.\n\n### Before calling\nAuthenticate with `collections:write` and resolve `placementId` from the same tenant. Choose `dryRun` for simulation or `queueOnly` for local queue evidence.\n\n### Request guidance\n`method` defaults to `mail` and must be `mail`, `email`, or `sms`. `dryRun` defaults to true. `queueOnly` defaults to false. Requests where both `dryRun` and `queueOnly` are false are rejected. If both `dryRun` and `queueOnly` are true, dry-run behavior wins and the response status remains `SIMULATED_ONLY`; only `queueOnly: true` with `dryRun: false` appends local queue evidence. `idempotencyKey` is accepted but no server-side replay/deduplication behavior is evidenced.\n\n### Request notes\n- Use dry-run mode for validation-only requests.\n- Use `queueOnly: true` and `dryRun: false` only when local queue evidence should be recorded.\n- Do not claim external mail, email, or SMS delivery from this response.\n- Do not put Protected Health Information (PHI) or credentials in `idempotencyKey`.\n\n### Response semantics\nThe response returns `placementId`, status `SIMULATED_ONLY` or `QUEUED`, `externalDelivery: NOT_SENT`, method, dryRun, and queueOnly. It does not send mail, email, SMS, or agency portal messages.\n\n### Response notes\n- `externalDelivery` is always `NOT_SENT` in the public response schema.\n- `QUEUED` means local queue evidence only.\n- `SIMULATED_ONLY` means no local queue note was written by this public handler.\n\n### Errors and retries\nFix invalid mode combinations before retrying. Treat 404 as missing or wrong-organization placement. Queue-only requests mutate placement notes, so re-read after timeouts before retrying.\n\n### Error notes\n- 400 can indicate both `dryRun` and `queueOnly` are false.\n- 404 can indicate the placement is not visible to the authenticated organization.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"placementId","in":"path","description":"QuickRCM bad debt placement identifier. Placement read/write handlers look it up inside the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["mail","email","sms"],"default":"mail","description":"Requested notice channel enum: `mail`, `email`, or `sms`; defaults to `mail`."},"dryRun":{"type":"boolean","default":true,"description":"Safe simulation flag. Defaults to true and takes precedence when true."},"queueOnly":{"type":"boolean","default":false,"description":"Local queue-evidence flag. Defaults to false; only queues when true and `dryRun` is false."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":120,"description":"Optional caller retry marker capped at 120 characters. Current evidence does not show server-side deduplication."}}},"example":{"method":"mail","dryRun":true,"queueOnly":false,"idempotencyKey":"example-idempotencykey"}}},"description":"`method` defaults to `mail` and must be `mail`, `email`, or `sms`. `dryRun` defaults to true. `queueOnly` defaults to false. Requests where both `dryRun` and `queueOnly` are false are rejected. If both `dryRun` and `queueOnly` are true, dry-run behavior wins and the response status remains `SIMULATED_ONLY`; only `queueOnly: true` with `dryRun: false` appends local queue evidence. `idempotencyKey` is accepted but no server-side replay/deduplication behavior is evidenced."},"responses":{"200":{"description":"Validation notice request accepted safely","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"placementId":{"type":"string"},"status":{"type":"string","enum":["SIMULATED_ONLY","QUEUED"]},"externalDelivery":{"type":"string","enum":["NOT_SENT"]},"method":{"type":"string","enum":["mail","email","sms"]},"dryRun":{"type":"boolean"},"queueOnly":{"type":"boolean"}},"required":["placementId","status","externalDelivery","method","dryRun","queueOnly"]}},"required":["success","data"]},"example":{"success":true,"data":{"placementId":"00000000-0000-4000-8000-000000000001","status":"SIMULATED_ONLY","externalDelivery":"NOT_SENT","method":"mail","dryRun":true,"queueOnly":true}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Bad debt placement not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/compliance/rules":{"get":{"operationId":"listCollectionsComplianceRules","summary":"List collections compliance rules","description":"Lists collections compliance rules owned by the authenticated organization, optionally filtered by active state and rule type.\n\n### When to use\nUse this to populate compliance settings screens, audit configured contact restrictions, or inspect the rule set used by checkCollectionsCompliance.\n\n### Before calling\nAuthenticate with Collections read or write access. Decide whether to filter on `isActive` or `ruleType`; no pagination is declared.\n\n### Request guidance\n`isActive` is coerced from the query value when supplied. `ruleType` is an optional trimmed string capped at 80 characters. Do not send an organization selector.\n\n### Request notes\n- Use `isActive=true` to inspect rules that can affect checks.\n- Use checkCollectionsCompliance to evaluate a contact scenario against active rules.\n- Rule type values are organization-local strings; common examples may include Fair Debt Collection Practices Act (FDCPA), Telephone Consumer Protection Act (TCPA), or custom labels.\n\n### Response semantics\nThe response returns `data.rules`, an array of local compliance rule records with threshold fields, state, active flag, and timestamps.\n\n### Response notes\n- Returned rules are local configuration, not legal advice.\n- Threshold fields can be null.\n\n### Errors and retries\nCorrect invalid query values before retrying. Treat 429 as a backoff signal.\n\n### Error notes\n- 403 means insufficient Collections access.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":["boolean","null"]},"required":false,"name":"isActive","in":"query","description":"Optional query filter for active or inactive local compliance rules."},{"schema":{"type":"string","minLength":1,"maxLength":80},"required":false,"name":"ruleType","in":"query","description":"Optional organization-local compliance rule type filter."}],"responses":{"200":{"description":"Collections compliance rules","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"ruleName":{"type":"string"},"ruleType":{"type":"string"},"description":{"type":["string","null"]},"maxCallsPerWeek":{"type":["integer","null"]},"noCallBeforeHour":{"type":["integer","null"]},"noCallAfterHour":{"type":["integer","null"]},"debtValidationDays":{"type":["integer","null"]},"state":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","ruleName","ruleType","description","maxCallsPerWeek","noCallBeforeHour","noCallAfterHour","debtValidationDays","state","isActive","createdAt","updatedAt"]}}},"required":["rules"]}},"required":["success","data"]},"example":{"success":true,"data":{"rules":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","ruleName":"Example collections_compliance_rule","ruleType":"example-ruletype","description":"Example collections_compliance_rule note","maxCallsPerWeek":1,"noCallBeforeHour":1,"noCallAfterHour":1,"debtValidationDays":1,"state":"example-state","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createCollectionsComplianceRule","summary":"Create collections compliance rule","description":"Creates a local collections compliance rule inside the authenticated organization.\n\n### When to use\nUse this when an organization needs configurable local restrictions for collections contact windows, call counts, debt validation timing, state-specific policy, Telephone Consumer Protection Act (TCPA)-style consent handling, Fair Debt Collection Practices Act (FDCPA)-style rules, or other internal compliance classifications.\n\n### Before calling\nAuthenticate with `collections:write`. Choose a reusable `ruleName` and `ruleType`; set optional thresholds only when they match organization policy.\n\n### Request guidance\n`ruleName` and `ruleType` are required. Optional threshold fields are integer-bounded: `maxCallsPerWeek` 0 through 100, `noCallBeforeHour` and `noCallAfterHour` 0 through 23, `debtValidationDays` 0 through 365, and two-character `state`. `isActive` defaults to true when omitted.\n\n### Request notes\n- Use full legal names on first mention in docs: Telephone Consumer Protection Act (TCPA) and Fair Debt Collection Practices Act (FDCPA).\n- Keep rule descriptions concise and policy-focused.\n- Do not encode patient-specific facts or legal conclusions in rule metadata.\n\n### Response semantics\nA 201 response returns the created local rule. The rule can affect future compliance checks but does not itself contact patients, agencies, payers, or regulators.\n\n### Response notes\n- The returned rule is local configuration.\n- `isActive` defaults to true when omitted.\n\n### Errors and retries\nFix 400 validation failures before retrying. After timeouts, list rules before creating another similarly named rule because no idempotency key is declared.\n\n### Error notes\n- 400 can indicate missing required name/type or out-of-range threshold fields.\n- 403 means the caller lacks Collections write access.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ruleName":{"type":"string","minLength":1,"maxLength":200,"description":"Required human-readable collections compliance rule name."},"ruleType":{"type":"string","minLength":1,"maxLength":80,"description":"Required organization-local collections compliance rule classification string."},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional rule description capped at 1000 characters."},"maxCallsPerWeek":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Optional threshold from 0 through 100."},"noCallBeforeHour":{"type":["integer","null"],"minimum":0,"maximum":23,"description":"Optional earliest contact hour in 24-hour local time, from 0 through 23."},"noCallAfterHour":{"type":["integer","null"],"minimum":0,"maximum":23,"description":"Optional latest contact hour in 24-hour local time, from 0 through 23."},"debtValidationDays":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Optional debt validation threshold from 0 through 365."},"state":{"type":"string","minLength":2,"maxLength":2,"description":"Optional two-character state code for state-specific policy."},"isActive":{"type":"boolean","description":"Schedule active-state boolean. Schedule create defaults to true; pause/resume endpoints also mutate active state."}},"required":["ruleName","ruleType"]},"example":{"ruleName":"Example collections_compliance_rule","ruleType":"example-ruletype","description":"Example collections_compliance_rule note","maxCallsPerWeek":1,"noCallBeforeHour":1,"noCallAfterHour":1,"debtValidationDays":1,"state":"example-state","isActive":true}}},"description":"`ruleName` and `ruleType` are required. Optional threshold fields are integer-bounded: `maxCallsPerWeek` 0 through 100, `noCallBeforeHour` and `noCallAfterHour` 0 through 23, `debtValidationDays` 0 through 365, and two-character `state`. `isActive` defaults to true when omitted."},"responses":{"201":{"description":"Collections compliance rule created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"ruleName":{"type":"string"},"ruleType":{"type":"string"},"description":{"type":["string","null"]},"maxCallsPerWeek":{"type":["integer","null"]},"noCallBeforeHour":{"type":["integer","null"]},"noCallAfterHour":{"type":["integer","null"]},"debtValidationDays":{"type":["integer","null"]},"state":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","ruleName","ruleType","description","maxCallsPerWeek","noCallBeforeHour","noCallAfterHour","debtValidationDays","state","isActive","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","ruleName":"Example collections_compliance_rule","ruleType":"example-ruletype","description":"Example collections_compliance_rule note","maxCallsPerWeek":1,"noCallBeforeHour":1,"noCallAfterHour":1,"debtValidationDays":1,"state":"example-state","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/compliance/rules/{ruleId}":{"get":{"operationId":"getCollectionsComplianceRule","summary":"Get collections compliance rule","description":"Returns one collections compliance rule when `ruleId` belongs to the authenticated organization.\n\n### When to use\nUse this after listing or creating rules when you need the current local rule definition before update or deactivation.\n\n### Before calling\nAuthenticate with Collections read or write access and use a rule id from the same tenant context.\n\n### Request guidance\nPass `ruleId` in the path. Do not include organization selectors or legal-document payloads.\n\n### Request notes\n- `ruleId` must be non-empty.\n- Use checkCollectionsCompliance to evaluate contact scenarios.\n\n### Response semantics\nThe response returns a local compliance rule with threshold fields and active status. It is configuration evidence, not a compliance guarantee.\n\n### Response notes\n- Nullable threshold fields mean no configured threshold for that field.\n- The response does not evaluate a patient contact scenario.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization rule context. Retry only transient 5xx or 429 responses.\n\n### Error notes\n- 404 means the rule was not found in the authenticated organization.\n- 401 and 403 require credential or scope correction.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ruleId","in":"path","description":"QuickRCM collections compliance rule identifier from the path."}],"responses":{"200":{"description":"Collections compliance rule","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"ruleName":{"type":"string"},"ruleType":{"type":"string"},"description":{"type":["string","null"]},"maxCallsPerWeek":{"type":["integer","null"]},"noCallBeforeHour":{"type":["integer","null"]},"noCallAfterHour":{"type":["integer","null"]},"debtValidationDays":{"type":["integer","null"]},"state":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","ruleName","ruleType","description","maxCallsPerWeek","noCallBeforeHour","noCallAfterHour","debtValidationDays","state","isActive","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","ruleName":"Example collections_compliance_rule","ruleType":"example-ruletype","description":"Example collections_compliance_rule note","maxCallsPerWeek":1,"noCallBeforeHour":1,"noCallAfterHour":1,"debtValidationDays":1,"state":"example-state","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Collections compliance rule not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"updateCollectionsComplianceRule","summary":"Update collections compliance rule","description":"Replaces the editable body-backed fields on a collections compliance rule after an organization-scoped rule lookup.\n\n### When to use\nUse this when an existing local compliance rule needs a new name, type, threshold set, state, description, or active flag.\n\n### Before calling\nAuthenticate with `collections:write`, retrieve the existing rule, and send the intended complete rule body. This endpoint is not a partial PATCH.\n\n### Request guidance\n`ruleName` and `ruleType` are required on update. Omitted optional fields are written as null by the current upsert path: `description`, `maxCallsPerWeek`, `noCallBeforeHour`, `noCallAfterHour`, `debtValidationDays`, and `state`. Omitted `isActive` defaults to true, which can reactivate a previously disabled rule. Include every value you want to preserve.\n\n### Request notes\n- Always send the full intended rule state.\n- Include `isActive: false` explicitly when the rule should remain disabled.\n- Do not describe this endpoint as a PATCH-style partial update.\n\n### Response semantics\nThe response returns the updated local rule. The update can affect future compliance checks but does not retroactively update past check results or perform outreach.\n\n### Response notes\n- Returned threshold fields reflect replacement semantics.\n- The returned rule is local configuration, not legal advice.\n\n### Errors and retries\nTreat 400 as missing required ruleName/ruleType or invalid threshold values. Treat 404 as missing or wrong-organization rule context. Re-read after timeouts before retrying to avoid clearing or reactivating fields unintentionally.\n\n### Error notes\n- 400 can indicate required fields were omitted even though the route is named update.\n- 404 can hide wrong-tenant rule identifiers.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ruleId","in":"path","description":"QuickRCM collections compliance rule identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ruleName":{"type":"string","minLength":1,"maxLength":200,"description":"Required on update. Human-readable rule name to store."},"ruleType":{"type":"string","minLength":1,"maxLength":80,"description":"Required on update. Organization-local rule classification to store."},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"maxCallsPerWeek":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Optional collections compliance rule threshold for maximum weekly calls, from 0 through 100."},"noCallBeforeHour":{"type":["integer","null"],"minimum":0,"maximum":23,"description":"Optional earliest contact hour in 24-hour local time, from 0 through 23."},"noCallAfterHour":{"type":["integer","null"],"minimum":0,"maximum":23,"description":"Optional latest contact hour in 24-hour local time, from 0 through 23."},"debtValidationDays":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Optional compliance rule threshold for debt validation timing, from 0 through 365."},"state":{"type":"string","minLength":2,"maxLength":2,"description":"US state, provider state, submitter state, or workflow state depending on context."},"isActive":{"type":"boolean","description":"Optional in schema but defaults to true when omitted by the current upsert path; send false explicitly to keep a rule inactive."}},"required":["ruleName","ruleType"]},"example":{"ruleName":"Example collections_compliance_rule","ruleType":"example-ruletype","description":"Example collections_compliance_rule note","maxCallsPerWeek":1,"noCallBeforeHour":1,"noCallAfterHour":1,"debtValidationDays":1,"state":"example-state","isActive":true}}},"description":"`ruleName` and `ruleType` are required on update. Omitted optional fields are written as null by the current upsert path: `description`, `maxCallsPerWeek`, `noCallBeforeHour`, `noCallAfterHour`, `debtValidationDays`, and `state`. Omitted `isActive` defaults to true, which can reactivate a previously disabled rule. Include every value you want to preserve."},"responses":{"200":{"description":"Collections compliance rule updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"ruleName":{"type":"string"},"ruleType":{"type":"string"},"description":{"type":["string","null"]},"maxCallsPerWeek":{"type":["integer","null"]},"noCallBeforeHour":{"type":["integer","null"]},"noCallAfterHour":{"type":["integer","null"]},"debtValidationDays":{"type":["integer","null"]},"state":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","ruleName","ruleType","description","maxCallsPerWeek","noCallBeforeHour","noCallAfterHour","debtValidationDays","state","isActive","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","ruleName":"Example collections_compliance_rule","ruleType":"example-ruletype","description":"Example collections_compliance_rule note","maxCallsPerWeek":1,"noCallBeforeHour":1,"noCallAfterHour":1,"debtValidationDays":1,"state":"example-state","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Collections compliance rule not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"delete":{"operationId":"deleteCollectionsComplianceRule","summary":"Deactivate collections compliance rule","description":"Soft-deactivates a collections compliance rule by marking it inactive after an organization-scoped lookup.\n\n### When to use\nUse this when a local rule should stop affecting future compliance checks but should remain in QuickRCM as historical configuration.\n\n### Before calling\nAuthenticate with `collections:write` and use a `ruleId` from the same organization.\n\n### Request guidance\nThe route has a required `ruleId` path parameter and an empty JSON body schema. Do not use this endpoint for hard deletion or legal hold removal.\n\n### Request notes\n- Use updateCollectionsComplianceRule with `isActive: true` to reactivate if needed.\n- No request body fields are declared.\n\n### Response semantics\nThe response returns `ruleId` and `isActive: false`. The rule is deactivated locally; it is not physically deleted by the public contract.\n\n### Response notes\n- `isActive` is always false in the success schema.\n- The operation is a soft deactivation.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization rule context. Re-reading the rule or list can confirm deactivation after a timeout.\n\n### Error notes\n- 404 means the rule was not found for the authenticated organization.\n- 403 means the caller lacks Collections write access.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ruleId","in":"path","description":"QuickRCM collections compliance rule identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"The route has a required `ruleId` path parameter and an empty JSON body schema. Do not use this endpoint for hard deletion or legal hold removal."},"responses":{"200":{"description":"Collections compliance rule deactivated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"ruleId":{"type":"string"},"isActive":{"type":"boolean","enum":[false]}},"required":["ruleId","isActive"]}},"required":["success","data"]},"example":{"success":true,"data":{"ruleId":"00000000-0000-4000-8000-000000000001","isActive":false}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Collections compliance rule not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/collections/compliance/check":{"post":{"operationId":"checkCollectionsCompliance","summary":"Check collections compliance","description":"Runs a local pre-contact collections compliance check for the authenticated organization using supplied patient/contact context, active rules, and optional placement enrichment.\n\n### When to use\nUse this before phone, text, email, or letter outreach when an integration needs QuickRCM's local allowed/violations/warnings decision for collections workflow controls.\n\n### Before calling\nAuthenticate with `collections:write`. Provide required `patientId` and `contactMethod`. Supply patient timezone, state, attorney, validation, call count, bankruptcy, deceased, dispute, and Telephone Consumer Protection Act (TCPA) context when available. If `placementId` is supplied and resolves in the authenticated organization, the handler can enrich missing attorney, bankruptcy, deceased, and dispute fields from that placement.\n\n### Request guidance\n`contactMethod` must be `phone`, `text`, `email`, or `letter`. `patientState` is a two-character string. `patientTimezone` is optional; the implementation falls back to `America/New_York` when absent. `daysSinceFirstContact` and `callsThisWeek` are non-negative integers. Optional date strings are not format-refined in the public schema, so use consistent ISO date or datetime strings. Do not treat an absent or wrong-tenant optional `placementId` as a hard failure; enrichment simply will not occur.\n\n### Request notes\n- Required fields are `patientId` and `contactMethod`.\n- Expand Telephone Consumer Protection Act (TCPA) and Fair Debt Collection Practices Act (FDCPA) on first use in final docs.\n- `placementId` is optional enrichment context, not a required selector.\n- Avoid logging raw patient identifiers or patient-contact context.\n\n### Response semantics\nA 200 response returns `allowed`, `violations`, and `warnings`. Each violation/warning contains ruleName, ruleType, severity, message, and nullable legalReference. The handler attempts to persist an audit log when the optional log entity is available, but audit-log persistence failure is non-fatal and the compliance decision is still returned. The response is local workflow guidance, not legal advice or a guarantee that future outreach is lawful.\n\n### Response notes\n- `allowed: false` means one or more local violations were returned.\n- `warnings` can be present even when `allowed` is true.\n- Do not present the result as legal advice or a regulatory guarantee.\n\n### Errors and retries\nFix missing required fields or invalid enum/bounds before retrying. Treat 429 as a backoff signal. Because compliance checks can write audit evidence, avoid tight repeated calls with identical patient/contact context.\n\n### Error notes\n- 400 can indicate missing patientId/contactMethod, invalid contactMethod, invalid state length, or negative count fields.\n- 403 means the caller lacks Collections write access.\n- 429 is the shared public API rate limit of 60 requests per minute.\n","tags":["Collections"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"Required QuickRCM patient identifier supplied for the contact scenario. Treat as patient-identifying in logs."},"contactMethod":{"type":"string","enum":["phone","text","email","letter"],"description":"Required proposed outreach channel: `phone`, `text`, `email`, or `letter`."},"patientTimezone":{"type":"string","minLength":1,"maxLength":80,"description":"Optional timezone string used for contact-window evaluation; implementation falls back to `America/New_York` when absent."},"patientState":{"type":"string","minLength":2,"maxLength":2,"description":"Optional two-character state used for state-specific local rule checks."},"patientHasAttorney":{"type":"boolean","description":"Optional contact-context flag indicating attorney representation."},"debtValidationSent":{"type":"boolean","description":"Optional input indicating whether debt validation has been sent or recorded."},"daysSinceFirstContact":{"type":["integer","null"],"minimum":0,"description":"Optional non-negative integer for debt validation timing checks."},"callsThisWeek":{"type":["integer","null"],"minimum":0,"description":"Optional non-negative integer for weekly call-count checks."},"bankruptcyFiled":{"type":"boolean"},"deceasedDate":{"type":"string","minLength":1},"disputedFlag":{"type":"boolean"},"disputeResolved":{"type":"boolean"},"tcpaConsentDate":{"type":"string","minLength":1,"description":"Optional date string indicating Telephone Consumer Protection Act consent context."},"tcpaOptOutDate":{"type":"string","minLength":1,"description":"Optional date string indicating Telephone Consumer Protection Act opt-out context."},"placementId":{"type":"string","minLength":1,"description":"QuickRCM bad debt placement identifier. Placement read/write handlers look it up inside the organization selected by the bearer API key."}},"required":["patientId","contactMethod"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","contactMethod":"phone","patientTimezone":"example-patienttimezone","patientState":"example-patientstate","patientHasAttorney":true,"debtValidationSent":true,"daysSinceFirstContact":1,"callsThisWeek":1,"bankruptcyFiled":true,"deceasedDate":"2026-06-08"}}},"description":"`contactMethod` must be `phone`, `text`, `email`, or `letter`. `patientState` is a two-character string. `patientTimezone` is optional; the implementation falls back to `America/New_York` when absent. `daysSinceFirstContact` and `callsThisWeek` are non-negative integers. Optional date strings are not format-refined in the public schema, so use consistent ISO date or datetime strings. Do not treat an absent or wrong-tenant optional `placementId` as a hard failure; enrichment simply will not occur."},"responses":{"200":{"description":"Collections compliance decision","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"allowed":{"type":"boolean"},"violations":{"type":"array","items":{"type":"object","properties":{"ruleName":{"type":"string"},"ruleType":{"type":"string"},"severity":{"type":"string"},"message":{"type":"string"},"legalReference":{"type":["string","null"]}},"required":["ruleName","ruleType","severity","message","legalReference"]}},"warnings":{"type":"array","items":{"type":"object","properties":{"ruleName":{"type":"string"},"ruleType":{"type":"string"},"severity":{"type":"string"},"message":{"type":"string"},"legalReference":{"type":["string","null"]}},"required":["ruleName","ruleType","severity","message","legalReference"]}}},"required":["allowed","violations","warnings"]}},"required":["success","data"]},"example":{"success":true,"data":{"allowed":true,"violations":[{"ruleName":"Example collections_compliance","ruleType":"example-ruletype","severity":"example-severity","message":"Request failed","legalReference":"example-legalreference"}],"warnings":[{"ruleName":"Example collections_compliance","ruleType":"example-ruletype","severity":"example-severity","message":"Request failed","legalReference":"example-legalreference"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/contract-management/contracts":{"get":{"operationId":"listContractManagementContracts","summary":"List insurance contracts","description":"Lists insurance contract summaries owned by the authenticated organization with optional filters for payer configuration, facility, active status, and base reimbursement type.\n\n### When to use\nUse this endpoint to populate contract inventory views, reconcile payer/facility contract coverage, find active or inactive contract records, or locate a contract before requesting detail.\n\n### Before calling\nAuthenticate with a tenant-scoped API key that has `contract-management:read` or `contract-management:write`. Decide the narrowest available payer, facility, active-state, or base-rate-type filter and use bounded pagination. The implementation rate-limits Contract Management public API calls to 60 requests per 60 seconds.\n\n### Request guidance\n`page` is one-based and defaults to 1. `pageSize` defaults to 25 and is capped at 100. `isActive` is a string query value and must be `true` or `false` when supplied. `baseRateType` must be one of the Contract Management rate type enum values. `payerConfigId` and `facilityId` are QuickRCM tenant-scoped identifiers, not external tenant selectors.\n\n### Request notes\n- Do not send `organizationId`; the API key selects the tenant.\n- `isActive` is not a boolean query value in the OpenAPI contract; send the string `true` or `false`.\n- Use `payerConfigId` and `facilityId` only after resolving those identifiers from the same tenant.\n\n### Response semantics\nThe response returns local QuickRCM contract summaries plus pagination metadata. Summary rows include contract identifiers, payer/facility summaries, effective and termination dates, active flag, base reimbursement type, decimal monetary strings, and a rate schedule count. `total` is the total count matching the filters, `pageSize` is the effective page size, and `totalPages` is computed from `total` and `pageSize`. The list response does not include the active rate schedule rows themselves.\n\n### Response notes\n- `data.contracts` is local contract inventory, not payer confirmation or contract-file evidence.\n- Monetary response fields such as `baseRate` and `medicarePercent` are decimal strings or null.\n- `payer.id` is the QuickRCM payer configuration id; `payer.payerId` is the optional external payer identifier stored on that payer configuration.\n- Use getContractManagementContract for the active rate schedule rows associated with one contract.\n\n### Errors and retries\nTreat 400 as invalid query or pagination input, 401 as missing or invalid bearer credentials, 403 as insufficient scope or tenant authorization failure, and 429 as a backoff signal. Retry only transient 5xx responses with normal client retry limits.\n\n### Error notes\n- 400 can indicate invalid `page`, `pageSize`, `isActive`, or `baseRateType` values.\n- 403 means the authenticated context cannot access the requested organization scope.\n- 429 should be retried with backoff rather than tight polling.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query","description":"One-based page number for contract list pagination. Defaults to 1."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"Maximum number of contracts to return. Defaults to 25 and cannot exceed 100. The response echoes the effective page size."},{"schema":{"type":"string","minLength":1},"required":false,"name":"payerConfigId","in":"query","description":"Optional QuickRCM payer configuration identifier. It must belong to the authenticated organization and is not the same field as `payer.payerId`."},{"schema":{"type":"string","minLength":1},"required":false,"name":"facilityId","in":"query","description":"Optional QuickRCM facility identifier. It must belong to the authenticated organization."},{"schema":{"type":"string","enum":["true","false"],"description":"Filters active status. Use \"true\" or \"false\"."},"required":false,"description":"Optional active-state filter. The public query schema accepts only the strings `true` and `false`.","name":"isActive","in":"query"},{"schema":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"]},"required":false,"name":"baseRateType","in":"query","description":"Optional base reimbursement type filter, such as `FEE_SCHEDULE`, `PER_DIEM`, `DRG_BASED`, `CASE_RATE`, `PERCENT_OF_CHARGE`, `MEDICARE_PERCENT`, `CAPITATED`, `STOP_LOSS`, `OUTLIER`, or `CARVE_OUT`."}],"responses":{"200":{"description":"Insurance contracts for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"contracts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"payerConfigId":{"type":"string"},"facilityId":{"type":["string","null"]},"contractName":{"type":"string"},"contractNumber":{"type":["string","null"]},"effectiveDate":{"type":"string","format":"date-time"},"terminationDate":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"baseRateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"]},"baseRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"medicarePercent":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payer":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":["string","null"]}},"required":["id","name","state"]},"rateSchedulesCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","payerConfigId","facilityId","contractName","contractNumber","effectiveDate","terminationDate","isActive","baseRateType","baseRate","medicarePercent","payer","facility","rateSchedulesCount","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1},"totalPages":{"type":"integer","minimum":0}},"required":["contracts","total","page","pageSize","totalPages"]}},"required":["success","data"]},"example":{"success":true,"data":{"contracts":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","contractName":"Example contract_management_contract","contractNumber":"example-contractnumber","effectiveDate":"2026-06-08T10:15:30Z","terminationDate":"2026-06-08T10:15:30Z","isActive":true,"baseRateType":"FEE_SCHEDULE","baseRate":"example-baserate","medicarePercent":"example-medicarepercent","payer":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example contract_management_contract","payerId":"87726"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example contract_management_contract","state":"example-state"},"rateSchedulesCount":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1,"totalPages":1}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createContractManagementContract","summary":"Create insurance contract","description":"Creates an organization-scoped insurance contract after validating the body and verifying the referenced payer configuration and optional facility are owned by the authenticated organization.\n\n### When to use\nUse this endpoint when an integration needs to create the local contract header that rate schedules, fee schedule imports, simulations, and underpayment workflows can reference later.\n\n### Before calling\nAuthenticate with `contract-management:write`. Resolve `payerConfigId` and optional `facilityId` from QuickRCM for the same tenant. Decide the base reimbursement type and effective date before creating the contract.\n\n### Request guidance\n`payerConfigId`, `contractName`, `effectiveDate`, and `baseRateType` are required. `contractName` is capped at 255 characters, `contractNumber` at 100, and `notes` at 10000. `effectiveDate` and `terminationDate` must be ISO datetimes. `baseRate` and `medicarePercent` are non-negative numeric inputs when supplied.\n\n### Request notes\n- `baseRateType` controls the primary reimbursement model label for the contract.\n- Do not put real contract PDFs, payer portal exports, credentials, or raw payer payloads in `notes`.\n- The body does not accept `organizationId`; tenant context comes from the bearer API key.\n- `payerConfigId` is a QuickRCM payer configuration id, not the optional external payer id shown as `payer.payerId` in responses.\n\n### Response semantics\nA 201 response returns the created local contract detail, including payer/facility summary and active rate schedule array. Newly created contract headers are marked active by the public handler. This endpoint does not upload a contract document, import fee schedule rows, or contact a payer. The implementation can return not-found errors when the payer configuration or facility fails the organization ownership check, but the current OpenAPI response map for this operation does not formally declare 404.\n\n### Response notes\n- `data.organizationId` is returned as record metadata and must match the authenticated organization.\n- `rateSchedules` is a local active schedule array and may be empty on a newly created contract.\n- Returned decimal values are strings even when request values were numeric.\n\n### Errors and retries\nFix validation failures before retrying 400 responses. Treat formally documented errors as 400, 401, 403, 429, and 500. If an implementation-observed not-found error occurs for a wrong-tenant or missing payer/facility, resolve the tenant-local identifiers before retrying. After a timeout, list contracts by payer/facility/name before creating another contract to avoid duplicates.\n\n### Error notes\n- 400 can indicate missing required fields, invalid date-time strings, invalid enum values, negative money fields, or excessive note/name length.\n- Implementation-observed 404 can indicate the payer configuration or facility was not found in the authenticated organization; update the OpenAPI response map before presenting that as a formal response code.\n- Retry transient failures only after checking whether the contract already exists.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payerConfigId":{"type":"string","minLength":1,"description":"Required QuickRCM payer configuration identifier. It must belong to the organization selected by the bearer API key."},"facilityId":{"type":["string","null"],"minLength":1,"description":"Optional QuickRCM facility identifier. When supplied, it must belong to the authenticated organization."},"contractName":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable local contract name, capped at 255 characters."},"contractNumber":{"type":["string","null"],"maxLength":100,"description":"Optional payer or internal contract number, capped at 100 characters."},"effectiveDate":{"type":"string","format":"date-time","description":"ISO datetime when the contract becomes effective."},"terminationDate":{"type":["string","null"],"format":"date-time","description":"Optional ISO datetime when the contract terminates; null means no termination date is recorded."},"baseRateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"],"description":"Primary reimbursement model for a contract or rate schedule: FEE_SCHEDULE, PER_DIEM, DRG_BASED, CASE_RATE, PERCENT_OF_CHARGE, MEDICARE_PERCENT, CAPITATED, STOP_LOSS, OUTLIER, or CARVE_OUT."},"baseRate":{"type":["number","null"],"minimum":0,"description":"Optional non-negative base rate input for reimbursement types that use an amount."},"medicarePercent":{"type":["number","null"],"minimum":0,"description":"Optional non-negative percentage input for Medicare-percent style contracts."},"notes":{"type":["string","null"],"maxLength":10000,"description":"Optional local contract notes. Keep notes free of secrets, raw payer payloads, and unnecessary PHI."}},"required":["payerConfigId","contractName","effectiveDate","baseRateType"]},"example":{"payerConfigId":"00000000-0000-4000-8000-000000000001","contractName":"Example contract_management_contract","effectiveDate":"2026-06-08T10:15:30Z","baseRateType":"FEE_SCHEDULE","facilityId":"00000000-0000-4000-8000-000000000001","contractNumber":"example-contractnumber","terminationDate":"2026-06-08T10:15:30Z","baseRate":1.25,"medicarePercent":1.25,"notes":"Example contract_management_contract note"}}},"description":"`payerConfigId`, `contractName`, `effectiveDate`, and `baseRateType` are required. `contractName` is capped at 255 characters, `contractNumber` at 100, and `notes` at 10000. `effectiveDate` and `terminationDate` must be ISO datetimes. `baseRate` and `medicarePercent` are non-negative numeric inputs when supplied."},"responses":{"201":{"description":"Insurance contract created for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"payerConfigId":{"type":"string"},"facilityId":{"type":["string","null"]},"contractName":{"type":"string"},"contractNumber":{"type":["string","null"]},"effectiveDate":{"type":"string","format":"date-time"},"terminationDate":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"baseRateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"]},"baseRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"medicarePercent":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payer":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":["string","null"]}},"required":["id","name","state"]},"rateSchedulesCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"rateSchedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"]},"code":{"type":"string"},"codeType":{"type":"string"},"description":{"type":["string","null"]},"rate":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"ratePercent":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"perDiemRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"caseRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"minRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"maxRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"terminationDate":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","rateType","code","codeType","description","rate","ratePercent","perDiemRate","caseRate","minRate","maxRate","effectiveDate","terminationDate","isActive","createdAt","updatedAt"]}}},"required":["id","organizationId","payerConfigId","facilityId","contractName","contractNumber","effectiveDate","terminationDate","isActive","baseRateType","baseRate","medicarePercent","payer","facility","rateSchedulesCount","createdAt","updatedAt","rateSchedules"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","contractName":"Example contract_management_contract","contractNumber":"example-contractnumber","effectiveDate":"2026-06-08T10:15:30Z","terminationDate":"2026-06-08T10:15:30Z","isActive":true,"baseRateType":"FEE_SCHEDULE","baseRate":"example-baserate","medicarePercent":"example-medicarepercent","payer":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example contract_management_contract","payerId":"87726"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example contract_management_contract","state":"example-state"},"rateSchedulesCount":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","rateSchedules":[{"id":"00000000-0000-4000-8000-000000000001","rateType":"FEE_SCHEDULE","code":"ERROR","codeType":"example-codetype","description":"Example contract_management_contract note","rate":"example-rate","ratePercent":"example-ratepercent","perDiemRate":"example-perdiemrate","caseRate":"example-caserate","minRate":"example-minrate","maxRate":"example-maxrate","effectiveDate":"2026-06-08T10:15:30Z","terminationDate":"2026-06-08T10:15:30Z","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/contract-management/contracts/{contractId}":{"get":{"operationId":"getContractManagementContract","summary":"Get insurance contract","description":"Returns one organization-owned insurance contract with its active rate schedules.\n\n### When to use\nUse this endpoint after a list response, create/update response, or trusted internal workflow gives you a `contractId` for the same tenant.\n\n### Before calling\nAuthenticate with `contract-management:read` or `contract-management:write` and use only a `contractId` obtained under the same API-key organization context.\n\n### Request guidance\nPass `contractId` in the path. No request body or functional query filters are declared for this endpoint. Do not include tenant selectors, payer credentials, raw contract documents, or vendor payloads.\n\n### Request notes\n- `contractId` is the only selector.\n- Do not guess contract identifiers across tenants.\n- No request body is declared.\n\n### Response semantics\nThe response returns the local contract detail plus active rate schedule rows. The current handler selects active schedules, orders them by code type and code, and caps returned rows at 100. Rate schedule monetary fields are decimal strings: `rate` is the primary amount, `ratePercent` is a percentage-style rate when applicable, `perDiemRate` is a daily rate, `caseRate` is a case-level amount, and `minRate`/`maxRate` are local bounds. The response is not proof that the payer accepts those terms.\n\n### Response notes\n- `rateSchedules` contains active local schedules only.\n- Rate values are returned as decimal strings.\n- `codeType` can label Current Procedural Terminology (CPT), Healthcare Common Procedure Coding System (HCPCS), Diagnosis-Related Group (DRG), or another local code-set category.\n- The response does not include contract-file contents or raw import files.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization contract context unless a prior trusted response proves the contract should exist. Retry only 429 or transient 5xx responses, with backoff.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant contracts.\n- 401 and 403 require credential, scope, or tenant-context correction.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"contractId","in":"path","description":"QuickRCM insurance contract identifier from the path. It must belong to the authenticated organization."}],"responses":{"200":{"description":"Insurance contract detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"payerConfigId":{"type":"string"},"facilityId":{"type":["string","null"]},"contractName":{"type":"string"},"contractNumber":{"type":["string","null"]},"effectiveDate":{"type":"string","format":"date-time"},"terminationDate":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"baseRateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"]},"baseRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"medicarePercent":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payer":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":["string","null"]}},"required":["id","name","state"]},"rateSchedulesCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"rateSchedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"]},"code":{"type":"string"},"codeType":{"type":"string"},"description":{"type":["string","null"]},"rate":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"ratePercent":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"perDiemRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"caseRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"minRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"maxRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"terminationDate":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","rateType","code","codeType","description","rate","ratePercent","perDiemRate","caseRate","minRate","maxRate","effectiveDate","terminationDate","isActive","createdAt","updatedAt"]}}},"required":["id","organizationId","payerConfigId","facilityId","contractName","contractNumber","effectiveDate","terminationDate","isActive","baseRateType","baseRate","medicarePercent","payer","facility","rateSchedulesCount","createdAt","updatedAt","rateSchedules"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","contractName":"Example contract_management_contract","contractNumber":"example-contractnumber","effectiveDate":"2026-06-08T10:15:30Z","terminationDate":"2026-06-08T10:15:30Z","isActive":true,"baseRateType":"FEE_SCHEDULE","baseRate":"example-baserate","medicarePercent":"example-medicarepercent","payer":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example contract_management_contract","payerId":"87726"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example contract_management_contract","state":"example-state"},"rateSchedulesCount":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","rateSchedules":[{"id":"00000000-0000-4000-8000-000000000001","rateType":"FEE_SCHEDULE","code":"ERROR","codeType":"example-codetype","description":"Example contract_management_contract note","rate":"example-rate","ratePercent":"example-ratepercent","perDiemRate":"example-perdiemrate","caseRate":"example-caserate","minRate":"example-minrate","maxRate":"example-maxrate","effectiveDate":"2026-06-08T10:15:30Z","terminationDate":"2026-06-08T10:15:30Z","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Insurance contract not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"updateContractManagementContract","summary":"Update insurance contract","description":"Updates editable fields on one organization-owned insurance contract and records local audit evidence.\n\n### When to use\nUse this endpoint to correct local contract header metadata, activate or deactivate a contract, adjust dates, update the base reimbursement type, or revise sanitized notes.\n\n### Before calling\nAuthenticate with `contract-management:write`, load the current contract state, and decide the minimal set of fields to change. The public body does not support changing `payerConfigId` or `facilityId`.\n\n### Request guidance\nPass `contractId` in the path and at least one editable field in the body. Editable fields are `contractName`, `contractNumber`, `effectiveDate`, `terminationDate`, `isActive`, `baseRateType`, `baseRate`, `medicarePercent`, and `notes`.\n\n### Request notes\n- Use PUT for the update route.\n- Send only fields you intend to change.\n- Do not include payer credentials, raw contract text, or PHI-rich dispute context in `notes`.\n\n### Response semantics\nA successful response returns the updated local contract detail with active rate schedules. It does not import rates, re-run simulations, notify payers, or rewrite existing underpayment cases.\n\n### Response notes\n- The response is local contract state after update.\n- Existing rate schedule rows are not modified by this endpoint.\n- Changed fields are recorded in a local audit log by the handler.\n\n### Errors and retries\nA 400 can mean the body contained no editable fields or a value failed schema validation. Treat 404 as missing or wrong-tenant contract context. Re-read the contract after timeouts before retrying to avoid overwriting concurrent admin changes.\n\n### Error notes\n- 400 can indicate an empty update body.\n- 404 can mean the contract does not exist or is outside the authenticated organization.\n- Retry after a read if the previous request may have succeeded.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"contractId","in":"path","description":"QuickRCM insurance contract identifier from the path. It must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contractName":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable local insurance contract name."},"contractNumber":{"type":["string","null"],"maxLength":100,"description":"Optional payer or internal contract number. Treat as contract metadata, not a tenant selector."},"effectiveDate":{"type":"string","format":"date-time","description":"ISO datetime when a contract or fee schedule becomes effective."},"terminationDate":{"type":["string","null"],"format":"date-time","description":"Optional ISO datetime when a contract terminates. Null means no termination date is recorded."},"isActive":{"type":"boolean","description":"Boolean flag indicating whether the contract is active for local workflows."},"baseRateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"],"description":"Updated base reimbursement type for the contract header. It must be one of the Contract Management rate type enum values."},"baseRate":{"type":["number","null"],"minimum":0,"description":"Optional base reimbursement amount for a contract. Request values are non-negative numbers; response values are decimal strings or null."},"medicarePercent":{"type":["number","null"],"minimum":0,"description":"Optional Medicare percentage value for applicable contract reimbursement models. Request values are non-negative numbers; response values are decimal strings or null."},"notes":{"type":["string","null"],"maxLength":10000,"description":"Optional local notes field, capped at 10000 characters."}}},"example":{"contractName":"Example contract_management_contract","contractNumber":"example-contractnumber","effectiveDate":"2026-06-08T10:15:30Z","terminationDate":"2026-06-08T10:15:30Z","isActive":true,"baseRateType":"FEE_SCHEDULE","baseRate":1.25,"medicarePercent":1.25}}},"description":"Pass `contractId` in the path and at least one editable field in the body. Editable fields are `contractName`, `contractNumber`, `effectiveDate`, `terminationDate`, `isActive`, `baseRateType`, `baseRate`, `medicarePercent`, and `notes`."},"responses":{"200":{"description":"Updated insurance contract for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"payerConfigId":{"type":"string"},"facilityId":{"type":["string","null"]},"contractName":{"type":"string"},"contractNumber":{"type":["string","null"]},"effectiveDate":{"type":"string","format":"date-time"},"terminationDate":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"baseRateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"]},"baseRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"medicarePercent":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payer":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":["string","null"]}},"required":["id","name","state"]},"rateSchedulesCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"rateSchedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"]},"code":{"type":"string"},"codeType":{"type":"string"},"description":{"type":["string","null"]},"rate":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"ratePercent":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"perDiemRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"caseRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"minRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"maxRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"terminationDate":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","rateType","code","codeType","description","rate","ratePercent","perDiemRate","caseRate","minRate","maxRate","effectiveDate","terminationDate","isActive","createdAt","updatedAt"]}}},"required":["id","organizationId","payerConfigId","facilityId","contractName","contractNumber","effectiveDate","terminationDate","isActive","baseRateType","baseRate","medicarePercent","payer","facility","rateSchedulesCount","createdAt","updatedAt","rateSchedules"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","contractName":"Example contract_management_contract","contractNumber":"example-contractnumber","effectiveDate":"2026-06-08T10:15:30Z","terminationDate":"2026-06-08T10:15:30Z","isActive":true,"baseRateType":"FEE_SCHEDULE","baseRate":"example-baserate","medicarePercent":"example-medicarepercent","payer":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example contract_management_contract","payerId":"87726"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example contract_management_contract","state":"example-state"},"rateSchedulesCount":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","rateSchedules":[{"id":"00000000-0000-4000-8000-000000000001","rateType":"FEE_SCHEDULE","code":"ERROR","codeType":"example-codetype","description":"Example contract_management_contract note","rate":"example-rate","ratePercent":"example-ratepercent","perDiemRate":"example-perdiemrate","caseRate":"example-caserate","minRate":"example-minrate","maxRate":"example-maxrate","effectiveDate":"2026-06-08T10:15:30Z","terminationDate":"2026-06-08T10:15:30Z","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Insurance contract not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/contract-management/simulations":{"post":{"operationId":"createContractManagementSimulation","summary":"Create rate simulation","description":"Creates a local what-if rate simulation draft for an organization-owned payer configuration.\n\n### When to use\nUse this endpoint when an integration wants to stage proposed Current Procedural Terminology (CPT) rate changes for later Contract Management analysis or review.\n\n### Before calling\nAuthenticate with `contract-management:write`. Resolve the request `payerId` from the tenant's QuickRCM payer configuration records and prepare 1 to 1000 proposed rate-change rows.\n\n### Request guidance\n`name`, `payerId`, and `rateChanges` are required. Each rate change requires `cptCode`, non-negative `currentRate`, and non-negative `proposedRate`. `cptCode` is capped at 20 characters. Despite the request field name, `payerId` is resolved by the current handler as a QuickRCM payer configuration id, not a clearinghouse payer id.\n\n### Request notes\n- The public field is named `payerId`, but the handler resolves it through organization-owned payer configuration lookup.\n- `rateChanges` accepts 1 through 1000 rows.\n- Keep simulation names and code labels operational and free of patient identifiers.\n\n### Response semantics\nA 201 response returns a local simulation record with status `CS_DRAFT`. `payerId` in the response is the stored QuickRCM payer configuration id and `payerName` is copied from that payer configuration. The public handler creates the draft and audit log only; it does not run the simulation, calculate final impact, contact a payer, or change contract rates. The implementation can return a not-found error for a missing payer configuration, but the current OpenAPI response map for this operation does not formally declare 404.\n\n### Response notes\n- `status` is `CS_DRAFT` on creation.\n- `totalImpact` and `annualClaimVolume` can be null until a later simulation process populates them.\n- No payer system is called.\n\n### Errors and retries\nFix invalid rate-change arrays before retrying. Treat formally documented errors as 400, 401, 403, 429, and 500. If an implementation-observed not-found error occurs for the payer selector, resolve the tenant-local payer configuration id before retrying. After a timeout, inspect recent simulations before creating another draft.\n\n### Error notes\n- 400 can indicate missing name, invalid payerId shape, empty rateChanges, too many rows, negative rates, or excessive cptCode length.\n- Implementation-observed 404 can indicate the payer configuration is unavailable in the authenticated organization; update the OpenAPI response map before presenting that as a formal response code.\n- Do not retry blindly after timeouts because duplicate drafts are possible.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable local simulation name, capped at 255 characters."},"payerId":{"type":"string","minLength":1,"description":"Endpoint-specific payer selector. In the current handler this is resolved as an organization-owned QuickRCM payer configuration identifier, not the nested `payer.payerId` external payer value from contract responses."},"rateChanges":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string","minLength":1,"maxLength":20,"description":"Current Procedural Terminology (CPT) or CPT-like procedure code for the proposed rate change, capped at 20 characters."},"currentRate":{"type":["number","null"],"minimum":0,"description":"Current non-negative rate value supplied by the caller for comparison."},"proposedRate":{"type":["number","null"],"minimum":0,"description":"Proposed non-negative rate value supplied by the caller for simulation."}},"required":["cptCode","currentRate","proposedRate"]},"minItems":1,"maxItems":1000,"description":"Array of proposed Current Procedural Terminology (CPT) rate changes. The public schema accepts 1 through 1000 entries."}},"required":["name","payerId","rateChanges"]},"example":{"name":"Example contract_management_simulation","payerId":"87726","rateChanges":[{"cptCode":"example-cptcode","currentRate":1.25,"proposedRate":1.25}]}}},"description":"`name`, `payerId`, and `rateChanges` are required. Each rate change requires `cptCode`, non-negative `currentRate`, and non-negative `proposedRate`. `cptCode` is capped at 20 characters. Despite the request field name, `payerId` is resolved by the current handler as a QuickRCM payer configuration id, not a clearinghouse payer id."},"responses":{"201":{"description":"Rate simulation created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]},"status":{"type":"string","enum":["CS_DRAFT","CS_RUNNING","CS_COMPLETED"]},"totalImpact":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"annualClaimVolume":{"type":["integer","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","payerId","payerName","status","totalImpact","annualClaimVolume","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example contract_management_simulation","payerId":"87726","payerName":"Example contract_management_simulation","status":"CS_DRAFT","totalImpact":"example-totalimpact","annualClaimVolume":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/contract-management/fee-schedules/import":{"post":{"operationId":"importContractManagementFeeSchedule","summary":"Validate or import fee schedule","description":"Validates fee schedule rows by default, or imports local fee schedule and rate rows when `validateOnly` is false.\n\n### When to use\nUse this endpoint to preflight a payer fee schedule import before creating local FeeSchedule, FeeScheduleRate, and FeeScheduleImport records for Contract Management workflows.\n\n### Before calling\nAuthenticate with `contract-management:write`. Resolve the request `payerId` from the authenticated organization's payer configuration records. Prepare a bounded array of structured entries instead of uploading a raw file.\n\n### Request guidance\n`validateOnly` defaults to true. Required fields are `payerId`, `name`, `effectiveDate`, and `entries`. Each entry requires `cptCode` and `allowedAmount`; optional entry fields are `modifier`, `facilityRate`, and `nonFacilityRate`. The schema accepts 1 through 10000 entries. `payerId` is resolved by the current handler as a QuickRCM payer configuration id, not a clearinghouse payer id.\n\n### Request notes\n- Use `validateOnly: true` for preflight and default behavior.\n- `scheduleType` defaults to `COMMERCIAL` in the handler when omitted during import.\n- Do not send raw payer files, PDFs, portal exports, S3 keys, or credentials in this JSON body.\n\n### Response semantics\nWhen `validateOnly` is true, the endpoint returns 200 with status `VALIDATED`, `entriesValidated`, and zero `entriesImported`; `feeScheduleId` and `importId` are absent or null because no records are created. When `validateOnly` is false, the endpoint creates local fee schedule records and returns 201 with status `IMPORTED`, `feeScheduleId`, and `importId`. The endpoint does not upload files or verify rates with a payer. The implementation can return a not-found error for a missing payer configuration, but the current OpenAPI response map for this operation does not formally declare 404.\n\n### Response notes\n- 200 means validation only; no fee schedule rows were imported.\n- 201 means local import records were created.\n- `feeScheduleId` identifies the local FeeSchedule created by a non-validation import.\n- `importId` identifies the local FeeScheduleImport audit/import record created by a non-validation import.\n- `entriesImported` is response metadata for the public import action, not payer acceptance evidence.\n\n### Errors and retries\nFix malformed rows before retrying 400 responses. Treat formally documented errors as 400, 401, 403, 429, and 500. If an implementation-observed not-found error occurs for the payer selector, resolve the tenant-local payer configuration id before retrying. After a timeout on `validateOnly: false`, check for an import record or fee schedule before retrying.\n\n### Error notes\n- 400 can indicate an invalid schedule type, invalid effectiveDate, empty entries, too many entries, negative amounts, or over-length CPT/modifier values.\n- Implementation-observed 404 can indicate the payer configuration is not in the authenticated organization; update the OpenAPI response map before presenting that as a formal response code.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","default":true,"description":"Boolean side-effect control. Defaults to true and validates rows without creating fee schedule records."},"payerId":{"type":"string","minLength":1,"description":"Endpoint-specific payer selector. In the current handler this is resolved as an organization-owned QuickRCM payer configuration identifier."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable local fee schedule name, capped at 255 characters."},"effectiveDate":{"type":"string","format":"date-time","description":"ISO datetime when the fee schedule becomes effective."},"scheduleType":{"type":"string","enum":["MEDICARE_MPFS","MEDICARE_OPPS","MEDICARE_ASC","MEDICAID_STATE","COMMERCIAL","WORKERS_COMP","TRICARE","VA","AUTO_PIP","CUSTOM"],"description":"Optional fee schedule type such as `MEDICARE_MPFS`, `MEDICARE_OPPS`, `MEDICARE_ASC`, `MEDICAID_STATE`, `COMMERCIAL`, `WORKERS_COMP`, `TRICARE`, `VA`, `AUTO_PIP`, or `CUSTOM`."},"entries":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string","minLength":1,"maxLength":20,"description":"Current Procedural Terminology (CPT) or CPT-like code for the fee schedule entry, capped at 20 characters."},"allowedAmount":{"type":["number","null"],"minimum":0,"description":"Required non-negative allowed amount for a fee schedule entry."},"modifier":{"type":["string","null"],"maxLength":10,"description":"Optional modifier string for a fee schedule entry, capped at 10 characters."},"facilityRate":{"type":["number","null"],"minimum":0,"description":"Optional non-negative facility-specific allowed amount."},"nonFacilityRate":{"type":["number","null"],"minimum":0,"description":"Optional non-negative non-facility allowed amount."}},"required":["cptCode","allowedAmount"]},"minItems":1,"maxItems":10000,"description":"Structured fee schedule entry array. The public schema accepts 1 through 10000 rows."}},"required":["payerId","name","effectiveDate","entries"]},"example":{"payerId":"87726","name":"Example import_contract_management_fee_schedule","effectiveDate":"2026-06-08T10:15:30Z","entries":[{"cptCode":"example-cptcode","allowedAmount":125.5,"modifier":"example-modifier","facilityRate":1.25,"nonFacilityRate":1.25}],"validateOnly":true,"scheduleType":"MEDICARE_MPFS"}}},"description":"`validateOnly` defaults to true. Required fields are `payerId`, `name`, `effectiveDate`, and `entries`. Each entry requires `cptCode` and `allowedAmount`; optional entry fields are `modifier`, `facilityRate`, and `nonFacilityRate`. The schema accepts 1 through 10000 entries. `payerId` is resolved by the current handler as a QuickRCM payer configuration id, not a clearinghouse payer id."},"responses":{"200":{"description":"Fee schedule import validation or import result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string"},"validateOnly":{"type":"boolean"},"entriesValidated":{"type":"integer","minimum":0},"entriesImported":{"type":"integer","minimum":0},"feeScheduleId":{"type":["string","null"]},"importId":{"type":["string","null"]}},"required":["status","validateOnly","entriesValidated","entriesImported"]}},"required":["success","data"]},"example":{"success":true,"data":{"status":"active","validateOnly":true,"entriesValidated":1,"entriesImported":1,"feeScheduleId":"00000000-0000-4000-8000-000000000001","importId":"00000000-0000-4000-8000-000000000001"}}}}},"201":{"description":"Fee schedule imported locally.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string"},"validateOnly":{"type":"boolean"},"entriesValidated":{"type":"integer","minimum":0},"entriesImported":{"type":"integer","minimum":0},"feeScheduleId":{"type":["string","null"]},"importId":{"type":["string","null"]}},"required":["status","validateOnly","entriesValidated","entriesImported"]}},"required":["success","data"]},"example":{"success":true,"data":{"status":"active","validateOnly":true,"entriesValidated":1,"entriesImported":1,"feeScheduleId":"00000000-0000-4000-8000-000000000001","importId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/contract-management/underpayments/detect":{"post":{"operationId":"detectContractManagementUnderpayments","summary":"Detect underpayments","description":"Runs an organization-scoped local scan of paid claims for potential underpayment cases, using `dryRun` by default.\n\n### When to use\nUse this endpoint to estimate or create local underpayment case candidates from recently paid claims before staff review and dispute workflows.\n\n### Before calling\nAuthenticate with `contract-management:write`. Start with `dryRun: true`. Decide whether to narrow by payer configuration, days-back window, and variance threshold. Do not use this endpoint as a full contract-rate resolver.\n\n### Request guidance\n`dryRun` defaults to true. `payerId` is optional and is applied as a QuickRCM payer configuration filter in the current handler. `daysBack` defaults to 90 and must be 1 through 365. `threshold` defaults to 5 and must be 0 through 100.\n\n### Request notes\n- Use `dryRun: true` unless explicitly creating local underpayment cases.\n- The handler currently caps the claim scan at 500 records.\n- `payerId` is a QuickRCM payer configuration id/filter in the current handler.\n- Do not describe this endpoint as a full contract-rate resolver, fee-schedule adjudicator, or payer audit.\n\n### Response semantics\nThe current handler scans up to 500 tenant-owned claims with status `PAID`, positive `totalPaid`, and `datesOfServiceStart` within the selected lookback window. For each claim it compares `totalCharges` and `totalPaid`, computes `((totalCharges - totalPaid) / totalCharges) * 100`, and counts candidates whose variance percent is greater than `threshold` and that do not already have an active underpayment case. The response returns whether the call was a dry run, how many paid claims were analyzed, how many cases would be created, and how many cases were created. When `dryRun` is false, the handler creates local `IDENTIFIED` cases with `underpaymentType: CONTRACT_VARIANCE`, `expectedAmount` equal to `totalCharges`, `paidAmount` equal to `totalPaid`, and `varianceAmount` equal to `totalCharges - totalPaid`.\n\n### Response notes\n- `casesWouldCreate` counts candidates after threshold and active-case checks.\n- `casesCreated` should be interpreted with the returned `dryRun` flag.\n- Created cases are local QuickRCM workflow records, not payer-submitted disputes.\n- The generated OpenAPI example can show `dryRun: true` with nonzero `casesCreated`; endpoint docs should define field semantics instead of treating that generated example as a behavioral guarantee.\n\n### Errors and retries\nTreat 400 as invalid scan parameters, 401/403 as credential or scope failures, and 429 as a backoff signal. If `dryRun` is false and the request times out, inspect underpayment cases before retrying to avoid duplicate operational work.\n\n### Error notes\n- 400 can indicate invalid `daysBack` or `threshold` values.\n- Retry non-dry-run calls only after checking current case state.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":true,"description":"Boolean side-effect control. Defaults to true and returns scan counts without creating cases."},"payerId":{"type":"string","minLength":1,"description":"Optional endpoint-specific payer selector. In the current handler this is applied as a QuickRCM `Claim.payerConfigId` filter for the authenticated organization."},"daysBack":{"type":"integer","minimum":1,"maximum":365,"default":90,"description":"Number of days of paid claims to scan, from 1 through 365. Defaults to 90."},"threshold":{"type":["number","null"],"minimum":0,"maximum":100,"default":5,"description":"Variance percentage threshold, from 0 through 100. The current handler creates/counts only candidates with variance percent greater than this value."}}},"example":{"dryRun":true,"payerId":"87726","daysBack":90,"threshold":5}}},"description":"`dryRun` defaults to true. `payerId` is optional and is applied as a QuickRCM payer configuration filter in the current handler. `daysBack` defaults to 90 and must be 1 through 365. `threshold` defaults to 5 and must be 0 through 100."},"responses":{"200":{"description":"Underpayment detection result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"dryRun":{"type":"boolean"},"claimsAnalyzed":{"type":"integer","minimum":0},"casesWouldCreate":{"type":"integer","minimum":0},"casesCreated":{"type":"integer","minimum":0}},"required":["dryRun","claimsAnalyzed","casesWouldCreate","casesCreated"]}},"required":["success","data"]},"example":{"success":true,"data":{"dryRun":true,"claimsAnalyzed":1,"casesWouldCreate":1,"casesCreated":1}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/contract-management/underpayment-cases/{caseId}/dispute-letter":{"post":{"operationId":"generateContractManagementDisputeLetter","summary":"Record dispute letter request","description":"Records a local dispute-letter request and audit activity for one organization-owned underpayment case.\n\n### When to use\nUse this endpoint when staff or automation wants to mark that a dispute letter should be prepared through a controlled local workflow.\n\n### Before calling\nAuthenticate with `contract-management:write` and resolve `caseId` from an underpayment case in the same tenant. Keep `queueOnly` true.\n\n### Request guidance\n`queueOnly` defaults to true and the current handler rejects `queueOnly: false`. `templateId` is optional request metadata. Do not include letter body content, raw payer responses, raw EDI, or file upload data.\n\n### Request notes\n- Always send or rely on `queueOnly: true`.\n- `templateId` is metadata only in the public request shape.\n- Do not send dispute letter contents through this endpoint.\n\n### Response semantics\nA 202 response returns status `REQUEST_RECORDED`, `queueOnly: true`, `caseId`, and `caseNumber`. The public API does not generate, upload, transmit, or return dispute-letter content.\n\n### Response notes\n- `REQUEST_RECORDED` means local activity/audit evidence was written.\n- No generated PDF, presigned URL, payer message, or EHR artifact is returned.\n- `caseNumber` is returned for operator reconciliation.\n\n### Errors and retries\nA 400 can indicate `queueOnly: false` or malformed request data. Treat 404 as missing or wrong-tenant underpayment case context. After timeouts, inspect case activity before recording another request.\n\n### Error notes\n- 400 can indicate an attempt to set `queueOnly` false.\n- 404 means the underpayment case did not resolve in the authenticated organization.\n- 429 should be retried with backoff.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"caseId","in":"path","description":"QuickRCM underpayment case identifier from the path. It must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Local side-effect control. The current public handler requires this to remain true."},"templateId":{"type":"string","minLength":1,"description":"Optional dispute-letter template identifier metadata. The public API does not return rendered template content."}}},"example":{"queueOnly":true,"templateId":"00000000-0000-4000-8000-000000000001"}}},"description":"`queueOnly` defaults to true and the current handler rejects `queueOnly: false`. `templateId` is optional request metadata. Do not include letter body content, raw payer responses, raw EDI, or file upload data."},"responses":{"202":{"description":"Dispute-letter request recorded locally.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["REQUEST_RECORDED"]},"queueOnly":{"type":"boolean"},"caseId":{"type":"string"},"caseNumber":{"type":"string"}},"required":["status","queueOnly","caseId","caseNumber"]}},"required":["success","data"]},"example":{"success":true,"data":{"status":"REQUEST_RECORDED","queueOnly":true,"caseId":"00000000-0000-4000-8000-000000000001","caseNumber":"example-casenumber"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Underpayment case not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/contract-management/underpayment-cases/{caseId}/assignment":{"put":{"operationId":"assignContractManagementUnderpaymentCase","summary":"Assign underpayment case","description":"Assigns one organization-owned underpayment case to an active member of the authenticated organization and records local activity/audit evidence.\n\n### When to use\nUse this endpoint for staff routing, supervisor assignment, work queue balancing, or moving an identified underpayment case into review.\n\n### Before calling\nAuthenticate with `contract-management:write`. Resolve the `caseId` in the same tenant and confirm the target `assigneeId` is an active organization member.\n\n### Request guidance\n`assigneeId` is required. The assignee must be an active organization member. When the existing case status is `IDENTIFIED`, the handler advances it to `UNDER_REVIEW`; otherwise the status is preserved.\n\n### Request notes\n- `caseId` selects the underpayment case in the path.\n- `assigneeId` must be a user id for an active member of the authenticated organization.\n- Assignment can move `IDENTIFIED` cases to `UNDER_REVIEW`.\n\n### Response semantics\nA successful response returns the local case id, assigned user id, and resulting status. It does not notify the assignee externally, submit an appeal, or contact a payer.\n\n### Response notes\n- The response is local assignment state.\n- Activity and audit logs are local QuickRCM evidence.\n- No payer or EHR workflow is executed by this assignment endpoint.\n\n### Errors and retries\nFix missing or inactive assignees before retrying 400 responses. Treat 404 as missing or wrong-tenant case context. Re-read the case after timeouts before retrying assignment.\n\n### Error notes\n- 400 can indicate the assignee is not an active member of the organization.\n- 404 can indicate the case is missing or outside the authenticated organization.\n- Retry only after reading current assignment state if the prior request may have succeeded.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"caseId","in":"path","description":"QuickRCM underpayment case identifier from the path. It must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assigneeId":{"type":"string","minLength":1,"description":"QuickRCM user identifier for the target assignee. The user must be an active member of the authenticated organization."}},"required":["assigneeId"]},"example":{"assigneeId":"00000000-0000-4000-8000-000000000001"}}},"description":"`assigneeId` is required. The assignee must be an active organization member. When the existing case status is `IDENTIFIED`, the handler advances it to `UNDER_REVIEW`; otherwise the status is preserved."},"responses":{"200":{"description":"Underpayment case assignment result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"assignedToId":{"type":["string","null"]},"status":{"type":"string"}},"required":["id","assignedToId","status"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","assignedToId":"00000000-0000-4000-8000-000000000001","status":"active"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Underpayment case not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/contract-management/underpayment-cases/{caseId}/resolve":{"put":{"operationId":"resolveContractManagementUnderpaymentCase","summary":"Resolve underpayment case","description":"Closes one organization-owned underpayment case with a recovery, write-off, or no-recovery resolution and records local activity/audit evidence.\n\n### When to use\nUse this endpoint after staff review determines that an underpayment case was recovered, should be written off, or should be closed without recovery.\n\n### Before calling\nAuthenticate with `contract-management:write`, read the current case, and verify it is not already resolved. Decide whether `resolvedAmount` is appropriate for recovered outcomes and keep notes sanitized.\n\n### Request guidance\n`resolution` is required and must be `RECOVERED`, `CLOSED_WRITE_OFF`, or `CLOSED_NO_RECOVERY`. `resolvedAmount` is optional and non-negative. `notes` is optional and capped at 2000 characters.\n\n### Request notes\n- `resolution` controls the final local case status.\n- `resolvedAmount` is stored as recovered amount only for recovered cases in the current handler.\n- Do not put raw payer responses, raw EDI, credentials, or unnecessary PHI in `notes`.\n\n### Response semantics\nA successful response returns the local case id, final status, and `resolvedAt` timestamp. This endpoint closes local workflow state; it does not post cash, update patient balances, transmit dispute results to an Electronic Health Record (EHR), or prove payer reimbursement.\n\n### Response notes\n- `resolvedAt` is an ISO datetime when the case was resolved.\n- The response is local case closure evidence.\n- Patient Accounts Receivable (AR), cash posting, appeal submission, and EHR write-back are separate workflows.\n\n### Errors and retries\nFix invalid resolution values, negative amounts, or excessive notes before retrying 400 responses. Treat 404 as missing or wrong-tenant case context. The current handler can reject already resolved cases as a conflict, but the OpenAPI response list should be updated before documenting 409 as a formal public response.\n\n### Error notes\n- 400 can indicate invalid request fields.\n- 404 can mean the case is missing or outside the authenticated organization.\n- Already-resolved cases can be rejected by the handler; keep the OpenAPI/implementation discrepancy explicit before publishing 409 details.\n","tags":["Contract Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"caseId","in":"path","description":"QuickRCM underpayment case identifier from the path. It must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string","enum":["RECOVERED","CLOSED_WRITE_OFF","CLOSED_NO_RECOVERY"],"description":"Required final resolution value: `RECOVERED`, `CLOSED_WRITE_OFF`, or `CLOSED_NO_RECOVERY`."},"resolvedAmount":{"type":["number","null"],"minimum":0,"description":"Optional non-negative recovery amount. In the current handler it is persisted as recovered amount only when resolution is `RECOVERED`."},"notes":{"type":"string","maxLength":2000,"description":"Optional sanitized local resolution note, capped at 2000 characters."}},"required":["resolution"]},"example":{"resolution":"RECOVERED","resolvedAmount":125.5,"notes":"Example contract_management_underpayment_case note"}}},"description":"`resolution` is required and must be `RECOVERED`, `CLOSED_WRITE_OFF`, or `CLOSED_NO_RECOVERY`. `resolvedAmount` is optional and non-negative. `notes` is optional and capped at 2000 characters."},"responses":{"200":{"description":"Underpayment case resolution result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","status","resolvedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","resolvedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Underpayment case not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions":{"get":{"operationId":"listCredentialingSessions","summary":"List credentialing sessions","description":"Returns paginated credentialing session summaries owned by the organization selected by the bearer API key, optionally filtered by credentialing session status.\n\n### When to use\nUse this endpoint to build a credentialing worklist, reconcile newly created sessions, or poll a bounded set of local session summaries before opening details.\n\n### Before calling\nAuthenticate with an API key that has `credentialing:read` or `credentialing:write`. Choose a specific `status` filter when possible and use `skip`/`take` pagination.\n\n### Request guidance\n`status` must be one of the public credentialing session statuses. `skip` defaults to 0 and is capped at 10000; `take` defaults to 50 and is capped at 100. Do not send `organizationId`; the bearer API key selects the tenant.\n\n### Request notes\n- Use status filters to keep worklists bounded.\n- The API key selects the organization; do not add a public organization selector.\n- Avoid logging raw search or workflow notes around credentialing sessions because they can contain provider-sensitive context.\n\n### Response semantics\nThe response contains local QuickRCM session summaries, `total`, `skip`, `take`, and `meta.organizationId`. Summary rows include provider summary fields, selected payer metadata, relation-level `documentCount`, attestation flag, and local timestamps; they do not prove payer enrollment, portal submission, document processing completion, or the active document detail list length.\n\n### Response notes\n- `data.sessions` is local QuickRCM credentialing state.\n- `documentCount` is the local documents relation count in the summary serializer, not proof that documents were externally submitted and not a promise that deleted rows are excluded.\n- `selectedPayers` contains local payer configuration links with nested `payerConfig.id`, `payerId`, and `payerName` when available.\n\n### Errors and retries\nTreat 400 as invalid filters or pagination, 401 as missing or invalid credentials, 403 as missing scope or tenant authorization failure, and 429 as a backoff signal. Retry transient 5xx responses with normal client retry limits.\n\n### Error notes\n- 429 means the public API key exceeded the request window and should be retried with backoff.\n- 403 can mean the key lacks both accepted Credentialing scopes.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["DRAFT","IN_PROGRESS","SUBMITTED","IN_REVIEW","ACCEPTED","COMPLETED","FAILED","DENIED","EXPIRED","ON_HOLD","REVOKED"]},"required":false,"name":"status","in":"query","description":"Optional local credentialing session status filter. Valid values are DRAFT, IN_PROGRESS, SUBMITTED, IN_REVIEW, ACCEPTED, COMPLETED, FAILED, DENIED, EXPIRED, ON_HOLD, and REVOKED."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"skip","in":"query","description":"Zero-based number of sessions to skip before returning the current page. The public schema caps this at 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"take","in":"query","description":"Maximum number of sessions to return. The public schema defaults to 50 and caps this at 100."}],"responses":{"200":{"description":"Credentialing sessions for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","IN_PROGRESS","SUBMITTED","IN_REVIEW","ACCEPTED","COMPLETED","FAILED","DENIED","EXPIRED","ON_HOLD","REVOKED"]},"statusNotes":{"type":["string","null"]},"providerName":{"type":["string","null"]},"providerInfo":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"npi":{"type":["string","null"]},"title":{"type":["string","null"]},"specialties":{"type":"array","items":{"type":"string"}},"languagesSpoken":{"type":"array","items":{"type":"string"}}},"required":["id","firstName","middleName","lastName","npi","title","specialties","languagesSpoken"]},"createdByUser":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"selectedPayers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["id","payerId","payerName"]}},"required":["id","payerConfigId","payerConfig"]}},"documentCount":{"type":"integer","minimum":0},"attestationAccepted":{"type":"boolean"},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","status","statusNotes","providerName","providerInfo","createdByUser","selectedPayers","documentCount","attestationAccepted","submittedAt","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["sessions","total","skip","take"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"sessions":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","statusNotes":"Example credentialing_session note","providerName":"Example credentialing_session","providerInfo":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","middleName":"Example credentialing_session","lastName":"Smith","npi":"1234567893","title":"Example credentialing_session","specialties":["example-specialties"],"languagesSpoken":["example-languagesspoken"]},"createdByUser":{"id":"00000000-0000-4000-8000-000000000001","name":"Example credentialing_session"},"selectedPayers":[{"id":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","payerName":"Example credentialing_session"}}],"documentCount":1,"attestationAccepted":true,"submittedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"skip":1,"take":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createCredentialingSession","summary":"Create credentialing session","description":"Creates a new local Credentialing session in DRAFT status for the organization selected by the bearer API key.\n\n### When to use\nUse this endpoint when an integration needs a new QuickRCM credentialing container before adding provider profile data, payer selections, documents, signature references, or attestation evidence.\n\n### Before calling\nAuthenticate with `credentialing:write`. Decide whether your next calls will populate session metadata, provider info, and required supporting records.\n\n### Request guidance\nThe public body schema has no fields. Send an empty JSON object if your client requires a body. Do not send `organizationId`, user IDs, credentialing status, payer portal credentials, or CAQH passwords.\n\n### Request notes\n- The request body is intentionally empty.\n- Tenant selection comes from the bearer API key.\n- Follow-up endpoints populate the provider packet.\n\n### Response semantics\nA successful response returns a local DRAFT session summary created for the API-key organization. The `createdByUser` value is the local actor user associated with the API-key context for audit/display purposes. No provider profile, payer, document, CAQH, signature, attestation, or portal side effects occur during the empty create.\n\n### Response notes\n- Returns `data.session` using the same summary schema as status/session update responses.\n- The new local status is DRAFT, with providerName null, providerInfo null, no selected payers, documentCount 0, attestationAccepted false, and submittedAt null until follow-up endpoints add data.\n- No external credentialing submission is performed.\n\n### Errors and retries\nTreat 401/403 as credential or scope issues. If a network failure occurs after sending the request, check the session list before blindly retrying because this create endpoint does not expose an idempotency key.\n\n### Error notes\n- Do not retry unknown create outcomes without checking for an existing created session.\n- 403 means the key lacks Credentialing write access.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"The public body schema has no fields. Send an empty JSON object if your client requires a body. Do not send `organizationId`, user IDs, credentialing status, payer portal credentials, or CAQH passwords."},"responses":{"201":{"description":"Credentialing session created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","IN_PROGRESS","SUBMITTED","IN_REVIEW","ACCEPTED","COMPLETED","FAILED","DENIED","EXPIRED","ON_HOLD","REVOKED"]},"statusNotes":{"type":["string","null"]},"providerName":{"type":["string","null"]},"providerInfo":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"npi":{"type":["string","null"]},"title":{"type":["string","null"]},"specialties":{"type":"array","items":{"type":"string"}},"languagesSpoken":{"type":"array","items":{"type":"string"}}},"required":["id","firstName","middleName","lastName","npi","title","specialties","languagesSpoken"]},"createdByUser":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"selectedPayers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["id","payerId","payerName"]}},"required":["id","payerConfigId","payerConfig"]}},"documentCount":{"type":"integer","minimum":0},"attestationAccepted":{"type":"boolean"},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","status","statusNotes","providerName","providerInfo","createdByUser","selectedPayers","documentCount","attestationAccepted","submittedAt","createdAt","updatedAt"]}},"required":["session"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"session":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","statusNotes":"Example credentialing_session note","providerName":"Example credentialing_session","providerInfo":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","middleName":"Example credentialing_session","lastName":"Smith","npi":"1234567893","title":"Example credentialing_session","specialties":["example-specialties"],"languagesSpoken":["example-languagesspoken"]},"createdByUser":{"id":"00000000-0000-4000-8000-000000000001","name":"Example credentialing_session"},"selectedPayers":[{"id":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","payerName":"Example credentialing_session"}}],"documentCount":1,"attestationAccepted":true,"submittedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}":{"get":{"operationId":"getCredentialingSession","summary":"Get credentialing session","description":"Returns one organization-owned Credentialing session with local document metadata when the session belongs to the API-key organization and is not soft-deleted.\n\n### When to use\nUse this after a list response, create response, webhook mapping, or user selection gives you a `sessionId` and you need session detail plus attached document summaries.\n\n### Before calling\nAuthenticate with `credentialing:read` or `credentialing:write`. Use a `sessionId` obtained from the same tenant context.\n\n### Request guidance\nPass only the path `sessionId`. Do not include payer portal credentials, CAQH secrets, raw file bytes, or tenant selectors.\n\n### Request notes\n- `sessionId` must come from a trusted QuickRCM response for the same tenant.\n- The endpoint has no query fields.\n- Wrong-organization IDs should resolve as not found.\n\n### Response semantics\nThe response contains local session detail plus `documents` filtered to non-deleted document rows and ordered newest-first by `createdAt`. Session detail keeps the summary providerInfo shape and adds document metadata; it does not return CAQH password material, raw binary files, extracted payloads, payer portal payloads, or external payer responses.\n\n### Response notes\n- `data.session.documents` contains active local document metadata only and is ordered newest-first.\n- Document `classificationStatus` and `extractionStatus` are local processing states; they are not payer submission evidence.\n- The session detail `providerInfo` object has the summary fields; use updateCredentialingProviderInfo responses for full provider info detail fields such as email, phoneNumber, race, previousName, and dateOfBirth.\n\n### Errors and retries\nTreat 404 as missing, wrong-organization, or soft-deleted session context. Retry transient 5xx responses, but do not retry malformed IDs unchanged.\n\n### Error notes\n- 404 can mean the record exists under another organization.\n- 401 and 403 require credential or scope correction before retry.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"responses":{"200":{"description":"Credentialing session detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","IN_PROGRESS","SUBMITTED","IN_REVIEW","ACCEPTED","COMPLETED","FAILED","DENIED","EXPIRED","ON_HOLD","REVOKED"]},"statusNotes":{"type":["string","null"]},"providerName":{"type":["string","null"]},"providerInfo":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"npi":{"type":["string","null"]},"title":{"type":["string","null"]},"specialties":{"type":"array","items":{"type":"string"}},"languagesSpoken":{"type":"array","items":{"type":"string"}}},"required":["id","firstName","middleName","lastName","npi","title","specialties","languagesSpoken"]},"createdByUser":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"selectedPayers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["id","payerId","payerName"]}},"required":["id","payerConfigId","payerConfig"]}},"documentCount":{"type":"integer","minimum":0},"attestationAccepted":{"type":"boolean"},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"documentType":{"type":["string","null"],"enum":["CV","DEA_CERTIFICATE","STATE_CDS_CERTIFICATE","BOARD_CERTIFICATION","MALPRACTICE_INSURANCE","PROFESSIONAL_REFERENCE","W9_TAX_FORM","VOIDED_CHECK","WORKERS_COMPENSATION","OTHER"]},"classificationStatus":{"type":"string","enum":["PENDING","CLASSIFIED","FAILED"]},"extractionStatus":{"type":"string","enum":["PENDING","EXTRACTING","COMPLETED","FAILED"]},"file":{"type":["object","null"],"properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]}},"required":["id","filename","mimeType","sizeBytes"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","documentType","classificationStatus","extractionStatus","file","createdAt","updatedAt"]}}},"required":["id","organizationId","status","statusNotes","providerName","providerInfo","createdByUser","selectedPayers","documentCount","attestationAccepted","submittedAt","createdAt","updatedAt","documents"]}},"required":["session"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"session":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","statusNotes":"Example credentialing_session note","providerName":"Example credentialing_session","providerInfo":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","middleName":"Example credentialing_session","lastName":"Smith","npi":"1234567893","title":"Example credentialing_session","specialties":["example-specialties"],"languagesSpoken":["example-languagesspoken"]},"createdByUser":{"id":"00000000-0000-4000-8000-000000000001","name":"Example credentialing_session"},"selectedPayers":[{"id":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","payerName":"Example credentialing_session"}}],"documentCount":1,"attestationAccepted":true,"submittedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","documents":[{"id":"00000000-0000-4000-8000-000000000001","documentType":"CV","classificationStatus":"PENDING","extractionStatus":"PENDING","file":{"id":"00000000-0000-4000-8000-000000000001","filename":"Example credentialing_session","mimeType":"example-mimetype","sizeBytes":1},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"updateCredentialingSession","summary":"Update credentialing session","description":"Updates public-safe session metadata for an organization-scoped Credentialing session, including status notes, display provider name, assignment, and selected payer configurations.\n\n### When to use\nUse this endpoint to add staff workflow context, assign a credentialing owner, or replace the selected payer configuration list before application readiness validation.\n\n### Before calling\nAuthenticate with `credentialing:write`. Confirm the session belongs to the API-key organization. Resolve assignee user IDs and payer configuration IDs from organization-owned QuickRCM records.\n\n### Request guidance\nSend only fields you intend to update. `payerConfigIds` replaces the selected payer links when provided; an empty array clears them. `assignedToId` must be an active organization member. `payerConfigIds` is capped at 100 and every payer config must belong to the organization.\n\n### Request notes\n- Omitted nullable fields are left unchanged.\n- `payerConfigIds` is replacement-style when present.\n- Use the status endpoint for lifecycle status changes.\n\n### Response semantics\nA successful response returns the updated local session summary. `selectedPayers` is returned as local session-payer link records with nested payer config id, payer id, and payer name when the payer config is available. The endpoint changes local metadata and payer selections; it does not submit the credentialing application or validate payer portal readiness.\n\n### Response notes\n- Returns `data.session` as a local summary.\n- Selected payer metadata is organization-local.\n- No external payer portal action is performed.\n- Returned providerInfo, createdByUser, selectedPayers, and documentCount are current summary state after the update; providerInfo itself is written by updateCredentialingProviderInfo, not by this endpoint unless already present.\n\n### Errors and retries\n400 can indicate an inactive assignee, invalid payer configuration, or request validation failure. 404 means the session was not found in the authenticated organization. Retry 5xx carefully after reloading current session state.\n\n### Error notes\n- 400 can mean selected payer IDs are not valid for this organization.\n- Do not retry stale full-object updates without reloading current session metadata.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"statusNotes":{"type":["string","null"],"maxLength":2000,"description":"Optional staff-facing credentialing status note. Keep it concise and avoid credentials or unnecessary sensitive detail."},"providerName":{"type":["string","null"],"maxLength":255,"description":"Optional local display name retained on the session. Structured provider details live under providerInfo."},"assignedToId":{"type":["string","null"],"minLength":1,"description":"QuickRCM user identifier for the staff member assigned to the credentialing session. The user must be an active member of the API-key organization."},"payerConfigIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":100,"description":"Array of organization-owned payer configuration IDs. When present, it replaces the session's selected payer links and is capped at 100 items."}}},"example":{"statusNotes":"Example credentialing_session note","providerName":"Example credentialing_session","assignedToId":"00000000-0000-4000-8000-000000000001","payerConfigIds":["example-payerconfigids"]}}},"description":"Send only fields you intend to update. `payerConfigIds` replaces the selected payer links when provided; an empty array clears them. `assignedToId` must be an active organization member. `payerConfigIds` is capped at 100 and every payer config must belong to the organization."},"responses":{"200":{"description":"Credentialing session updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","IN_PROGRESS","SUBMITTED","IN_REVIEW","ACCEPTED","COMPLETED","FAILED","DENIED","EXPIRED","ON_HOLD","REVOKED"]},"statusNotes":{"type":["string","null"]},"providerName":{"type":["string","null"]},"providerInfo":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"npi":{"type":["string","null"]},"title":{"type":["string","null"]},"specialties":{"type":"array","items":{"type":"string"}},"languagesSpoken":{"type":"array","items":{"type":"string"}}},"required":["id","firstName","middleName","lastName","npi","title","specialties","languagesSpoken"]},"createdByUser":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"selectedPayers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["id","payerId","payerName"]}},"required":["id","payerConfigId","payerConfig"]}},"documentCount":{"type":"integer","minimum":0},"attestationAccepted":{"type":"boolean"},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","status","statusNotes","providerName","providerInfo","createdByUser","selectedPayers","documentCount","attestationAccepted","submittedAt","createdAt","updatedAt"]}},"required":["session"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"session":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","statusNotes":"Example credentialing_session note","providerName":"Example credentialing_session","providerInfo":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","middleName":"Example credentialing_session","lastName":"Smith","npi":"1234567893","title":"Example credentialing_session","specialties":["example-specialties"],"languagesSpoken":["example-languagesspoken"]},"createdByUser":{"id":"00000000-0000-4000-8000-000000000001","name":"Example credentialing_session"},"selectedPayers":[{"id":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","payerName":"Example credentialing_session"}}],"documentCount":1,"attestationAccepted":true,"submittedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/documents":{"post":{"operationId":"createCredentialingDocument","summary":"Queue credentialing document upload","description":"Validates a credentialing document upload request for a tenant-owned session and returns a simulated queue response.\n\n### When to use\nUse this endpoint during public API pilots to validate file metadata and workflow ownership before enabling an implementation path that creates upload targets or file records.\n\n### Before calling\nAuthenticate with `credentialing:write`. Confirm the session exists in the API-key organization. Prepare metadata only; this endpoint does not accept raw file bytes.\n\n### Request guidance\n`queueOnly` must remain true. `fileType` must be application/pdf, image/png, image/jpeg, or image/tiff. `fileSize` must be positive and at most 50 MiB. `idempotencyKey` is accepted by the schema as a caller retry marker, but the current handler returns a simulation and does not persist de-duplication evidence.\n\n### Request notes\n- Send metadata only; do not send binary content.\n- `queueOnly` defaults to true and false is rejected.\n- `idempotencyKey` should not be documented as persisted de-duplication unless the handler changes.\n\n### Response semantics\nA 202 response returns `status: SIMULATED_ONLY`, `workflow: DOCUMENT_UPLOAD`, `sessionId`, and a message. It validates ownership and metadata but does not create File rows, CredentialingDocument rows, S3 objects, presigned upload URLs, or payer artifacts. Workflow responses use `data.status`, `data.workflow`, `data.message`, and the relevant `sessionId` or `documentId` identifier.\n\n### Response notes\n- 202 means the simulated workflow request was accepted.\n- No upload URL or storage key is returned.\n- No document record is created by the current public handler.\n\n### Errors and retries\n400 includes invalid metadata or `queueOnly: false`. 404 means the session was not found in the API-key organization. Back off on 429 and retry transient 5xx responses with normal limits.\n\n### Error notes\n- 400 can mean the file exceeds 50 MiB or uses an unsupported MIME type.\n- Do not retry with `queueOnly: false`.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Must be true for public Credentialing document upload validation. False is rejected."},"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Display filename for the planned credentialing document. Do not include unnecessary PHI or secrets in filenames."},"fileType":{"type":"string","enum":["application/pdf","image/png","image/jpeg","image/tiff"],"description":"Allowed MIME type for the planned document: application/pdf, image/png, image/jpeg, or image/tiff."},"fileSize":{"type":"integer","exclusiveMinimum":0,"maximum":52428800,"description":"Planned file size in bytes. The public schema accepts positive integers up to 52428800."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-provided retry marker accepted by the request schema. Current public simulation handling does not persist de-duplication state."}},"required":["fileName","fileType","fileSize"]},"example":{"fileName":"Example credentialing_document","fileType":"application/pdf","fileSize":1,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`queueOnly` must remain true. `fileType` must be application/pdf, image/png, image/jpeg, or image/tiff. `fileSize` must be positive and at most 50 MiB. `idempotencyKey` is accepted by the schema as a caller retry marker, but the current handler returns a simulation and does not persist de-duplication evidence."},"responses":{"202":{"description":"Document upload request accepted as a simulated queue-only workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","SIMULATED_ONLY","VALIDATED_ONLY"]},"workflow":{"type":"string"},"sessionId":{"type":"string"},"documentId":{"type":"string"},"message":{"type":"string"}},"required":["status","workflow","message"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"status":"SAFE_WRITE_DB_ONLY","workflow":"example-workflow","message":"Request failed","sessionId":"00000000-0000-4000-8000-000000000001","documentId":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/documents/{documentId}/process":{"post":{"operationId":"processCredentialingDocument","summary":"Queue credentialing document processing","description":"Validates ownership of a local credentialing document and returns a simulated document-processing workflow response.\n\n### When to use\nUse this endpoint to test or preview document processing orchestration after a document ID already exists in QuickRCM.\n\n### Before calling\nAuthenticate with `credentialing:write`. Use a document ID associated with a session in the API-key organization.\n\n### Request guidance\n`queueOnly` must remain true. The endpoint accepts `idempotencyKey` as a request-shape field, but it does not invoke OCR/extraction or persist an idempotent processing job in the current handler.\n\n### Request notes\n- `documentId` is in the path, not the body.\n- `queueOnly` defaults to true and false is rejected.\n- Do not send raw OCR text, transcripts, or vendor payloads.\n\n### Response semantics\nA 202 response returns `status: SIMULATED_ONLY`, `workflow: DOCUMENT_PROCESSING`, `documentId`, and a message. It does not update document classification, start OCR, run extraction, or return extracted document payloads. Workflow responses use `data.status`, `data.workflow`, `data.message`, and the relevant `sessionId` or `documentId` identifier.\n\n### Response notes\n- No OCR or extraction service is invoked.\n- No document status update is promised by this public endpoint.\n- The response is local workflow simulation metadata.\n\n### Errors and retries\n400 includes `queueOnly: false` or validation errors. 404 means the document was not found through the authenticated organization's session. Back off on 429 and avoid repeated simulation calls without purpose.\n\n### Error notes\n- 404 can mean the document belongs to another organization.\n- Do not retry authorization or ownership failures unchanged.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path","description":"QuickRCM Credentialing document identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Must be true for public Credentialing document processing simulation. False is rejected."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-provided retry marker accepted by the request schema. Current public simulation handling does not persist de-duplication state."}}},"example":{"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`queueOnly` must remain true. The endpoint accepts `idempotencyKey` as a request-shape field, but it does not invoke OCR/extraction or persist an idempotent processing job in the current handler."},"responses":{"202":{"description":"Document processing request accepted as a simulated queue-only workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","SIMULATED_ONLY","VALIDATED_ONLY"]},"workflow":{"type":"string"},"sessionId":{"type":"string"},"documentId":{"type":"string"},"message":{"type":"string"}},"required":["status","workflow","message"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"status":"SAFE_WRITE_DB_ONLY","workflow":"example-workflow","message":"Request failed","sessionId":"00000000-0000-4000-8000-000000000001","documentId":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing document not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/provider-info":{"put":{"operationId":"updateCredentialingProviderInfo","summary":"Update credentialing provider info","description":"Creates or updates structured provider profile fields for an organization-scoped Credentialing session.\n\n### When to use\nUse this endpoint to populate provider identity and contact fields needed before credentialing application readiness validation.\n\n### Before calling\nAuthenticate with `credentialing:write`. Confirm the session exists for the API-key organization and prepare only provider profile fields that should be stored.\n\n### Request guidance\nAll body fields are optional and nullable where declared. Date values are strings that the handler parses as dates; invalid date strings return 400. `specialties` is capped at 50 entries and each entry is capped at 255 characters. `languagesSpoken` is capped at 50 entries and each entry is capped at 100 characters.\n\n### Request notes\n- Send only profile fields you intend to create or update.\n- Use synthetic examples in documentation because provider profile fields can be sensitive.\n- `dateOfBirth` is provider credentialing context and should be protected in logs.\n\n### Response semantics\nThe response returns `data.providerInfo` with the full provider info detail shape: id, sessionId, name fields, NPI, title, dateOfBirth, race, previousName, specialties, languagesSpoken, email, phoneNumber, createdAt, and updatedAt. List and session summary responses intentionally expose only a smaller providerInfo summary shape.\n\n### Response notes\n- `data.providerInfo` is local QuickRCM profile state.\n- The response includes `sessionId` and timestamps.\n- No external identity verification is performed by this endpoint.\n\n### Errors and retries\n400 can indicate invalid email, invalid date, or array limits. 404 means the session was not found in the authenticated organization. Retry 5xx only after checking whether the profile already updated.\n\n### Error notes\n- 400 can include field-specific Zod validation or date parsing errors.\n- 404 can mean missing or wrong-tenant session.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":["string","null"],"maxLength":255,"description":"Provider first name for credentialing profile use. Nullable and capped at 255 characters; required by submit readiness when submitting an application."},"middleName":{"type":["string","null"],"maxLength":255,"description":"Optional provider middle name for credentialing profile use. Nullable and capped at 255 characters."},"lastName":{"type":["string","null"],"maxLength":255,"description":"Provider last name for credentialing profile use. Nullable and capped at 255 characters; required by submit readiness when submitting an application."},"npi":{"type":["string","null"],"maxLength":20,"description":"Provider National Provider Identifier string. Nullable and capped at 20 characters; required by submit readiness, but this endpoint does not verify NPI externally."},"title":{"type":["string","null"],"maxLength":50,"description":"Provider title or credential label, such as MD or DO. Nullable and capped at 50 characters."},"dateOfBirth":{"type":["string","null"],"minLength":1,"description":"Provider date-of-birth string parsed as a date. Treat as sensitive credentialing context and use synthetic examples only."},"race":{"type":["string","null"],"maxLength":100,"description":"Optional provider demographic field for credentialing forms. Nullable and capped at 100 characters; treat as sensitive demographic information."},"previousName":{"type":["string","null"],"maxLength":255,"description":"Optional prior provider name used for credentialing history. Nullable and capped at 255 characters; treat as sensitive identity context."},"specialties":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"maxItems":50,"description":"Array of provider specialty labels. The public schema caps this at 50 entries and each entry at 255 characters."},"languagesSpoken":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"description":"Array of provider language labels. The public schema caps this at 50 entries and each entry at 100 characters."},"email":{"type":["string","null"],"maxLength":255,"format":"email","description":"Provider email address for credentialing contact context. Nullable, must be valid email syntax when provided, and capped at 255 characters."},"phoneNumber":{"type":["string","null"],"maxLength":50,"description":"Provider contact phone number for credentialing workflow use. Nullable and capped at 50 characters."}}},"example":{"firstName":"John","middleName":"Example credentialing_provider_info","lastName":"Smith","npi":"1234567893","title":"Example credentialing_provider_info","dateOfBirth":"1984-03-22","race":"example-race","previousName":"Example credentialing_provider_info"}}},"description":"All body fields are optional and nullable where declared. Date values are strings that the handler parses as dates; invalid date strings return 400. `specialties` is capped at 50 entries and each entry is capped at 255 characters. `languagesSpoken` is capped at 50 entries and each entry is capped at 100 characters."},"responses":{"200":{"description":"Provider info updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"providerInfo":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"firstName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"npi":{"type":["string","null"]},"title":{"type":["string","null"]},"dateOfBirth":{"type":["string","null"],"format":"date-time"},"race":{"type":["string","null"]},"previousName":{"type":["string","null"]},"specialties":{"type":"array","items":{"type":"string"}},"languagesSpoken":{"type":"array","items":{"type":"string"}},"email":{"type":["string","null"]},"phoneNumber":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","firstName","middleName","lastName","npi","title","dateOfBirth","race","previousName","specialties","languagesSpoken","email","phoneNumber","createdAt","updatedAt"]}},"required":["providerInfo"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"providerInfo":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","firstName":"John","middleName":"Example credentialing_provider_info","lastName":"Smith","npi":"1234567893","title":"Example credentialing_provider_info","dateOfBirth":"1984-03-22","race":"example-race","previousName":"Example credentialing_provider_info","specialties":["example-specialties"],"languagesSpoken":["example-languagesspoken"],"email":"developer@example.com","phoneNumber":"+15551234567","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/caqh":{"put":{"operationId":"updateCredentialingCaqh","summary":"Update credentialing CAQH info","description":"Creates or updates non-secret CAQH metadata for an organization-scoped Credentialing session.\n\n### When to use\nUse this endpoint to store CAQH identifiers, username metadata, and attestation date tracking without transmitting passwords or portal secrets through the public API.\n\n### Before calling\nAuthenticate with `credentialing:write`. Confirm the session exists in the API-key organization. Keep CAQH passwords and portal credentials out of the request.\n\n### Request guidance\nOnly `caqhId`, `caqhUsername`, `lastAttestationDate`, and `nextAttestationDue` are accepted. Date values are parsed as dates by the handler. Do not send password fields, encrypted password material, MFA secrets, or payer portal credentials.\n\n### Request notes\n- The public API does not accept CAQH password fields.\n- `hasPassword` is response metadata, not a password value.\n- Use ISO date strings consistently for attestation dates.\n\n### Response semantics\nThe response returns `data.caqhInfo` with metadata and `hasPassword`. It intentionally omits password and encrypted password fields.\n\n### Response notes\n- Response omits CAQH password and encrypted password data.\n- Returned dates are nullable ISO datetimes when present.\n- This endpoint does not attest or submit CAQH data externally.\n\n### Errors and retries\n400 can indicate invalid date or field validation. 404 means the session was not found in the authenticated organization. Do not retry by adding secret fields.\n\n### Error notes\n- 400 can include invalid date parsing errors.\n- Credential or scope failures must be fixed before retry.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"caqhId":{"type":["string","null"],"maxLength":100,"description":"CAQH provider identifier metadata for the credentialing session. Nullable and capped at 100 characters; do not use it as a secret."},"caqhUsername":{"type":["string","null"],"maxLength":255,"description":"CAQH username metadata. Nullable and capped at 255 characters; treat as sensitive account context and never pair it with passwords in public API requests."},"lastAttestationDate":{"type":["string","null"],"minLength":1,"description":"Date string for the last known CAQH attestation date. Null clears the stored value; invalid date strings return 400."},"nextAttestationDue":{"type":["string","null"],"minLength":1,"description":"Date string for the next expected CAQH attestation due date. Null clears the stored value; invalid date strings return 400."}}},"example":{"caqhId":"00000000-0000-4000-8000-000000000001","caqhUsername":"Example credentialing_caqh","lastAttestationDate":"2026-06-08","nextAttestationDue":"example-nextattestationdue"}}},"description":"Only `caqhId`, `caqhUsername`, `lastAttestationDate`, and `nextAttestationDue` are accepted. Date values are parsed as dates by the handler. Do not send password fields, encrypted password material, MFA secrets, or payer portal credentials."},"responses":{"200":{"description":"CAQH info updated with secret fields omitted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"caqhInfo":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"caqhId":{"type":["string","null"]},"caqhUsername":{"type":["string","null"]},"hasPassword":{"type":"boolean"},"lastAttestationDate":{"type":["string","null"],"format":"date-time"},"nextAttestationDue":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","caqhId","caqhUsername","hasPassword","lastAttestationDate","nextAttestationDue","createdAt","updatedAt"]}},"required":["caqhInfo"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"caqhInfo":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","caqhId":"00000000-0000-4000-8000-000000000001","caqhUsername":"Example credentialing_caqh","hasPassword":true,"lastAttestationDate":"2026-06-08T10:15:30Z","nextAttestationDue":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/education":{"post":{"operationId":"createCredentialingEducation","summary":"Create credentialing education entry","description":"Adds an education history record to an organization-scoped Credentialing session.\n\n### When to use\nUse this endpoint when assembling a provider credentialing packet that needs medical school, residency, fellowship, or other education history entries.\n\n### Before calling\nAuthenticate with `credentialing:write`. Confirm the session exists in the API-key organization.\n\n### Request guidance\nSend the education fields that apply to the provider record. Date strings are parsed by the handler; invalid dates return 400. Do not send transcripts, diplomas, or binary files here.\n\n### Request notes\n- This endpoint stores structured education metadata only.\n- Use separate document workflows for supporting files.\n- The request body has no public organization selector.\n\n### Response semantics\nA 201 response returns `data.record` for the newly created local education entry with `sessionId`, `sortOrder`, timestamps, and supplied fields. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- `data.record` is local subresource state.\n- `sortOrder` is server-assigned workflow ordering metadata.\n- No external verification is performed.\n\n### Errors and retries\n400 can indicate invalid dates or field limits. 404 means the session was not found in the authenticated organization. If a retry could duplicate an education row, list or inspect the session before retrying.\n\n### Error notes\n- Do not retry unknown create outcomes without checking for duplicates.\n- 404 can mean wrong-tenant session.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"educationType":{"type":["string","null"],"maxLength":255,"description":"Education category or training type for the credentialing packet. Nullable and capped at 255 characters."},"degree":{"type":["string","null"],"maxLength":255,"description":"Degree or credential label for the education entry. Nullable and capped at 255 characters."},"institutionName":{"type":["string","null"],"maxLength":255,"description":"Institution name for the education entry. Nullable and capped at 255 characters."},"startDate":{"type":["string","null"],"minLength":1,"description":"Start date string for the education period. Null clears the value; invalid date strings return 400."},"endDate":{"type":["string","null"],"minLength":1,"description":"End date string for the education period. Use null for open or unknown dates when appropriate; invalid date strings return 400."}}},"example":{"educationType":"example-educationtype","degree":"example-degree","institutionName":"Example credentialing_education","startDate":"2026-06-08","endDate":"2026-06-08"}}},"description":"Send the education fields that apply to the provider record. Date strings are parsed by the handler; invalid dates return 400. Do not send transcripts, diplomas, or binary files here."},"responses":{"201":{"description":"Education entry created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/education/{educationId}":{"put":{"operationId":"updateCredentialingEducation","summary":"Update credentialing education entry","description":"Updates a local education history record after verifying it belongs to a session in the API-key organization.\n\n### When to use\nUse this endpoint to correct or complete an existing credentialing education entry.\n\n### Before calling\nAuthenticate with `credentialing:write`. Use an `educationId` previously returned by QuickRCM for the same organization.\n\n### Request guidance\nSend only the fields to update. Date fields are parsed and invalid dates return 400. This endpoint does not accept document uploads or external verification payloads.\n\n### Request notes\n- `educationId` is scoped through the parent session organization.\n- Omitted fields are left unchanged.\n- Use null for nullable fields that should be cleared.\n\n### Response semantics\nA successful response returns the updated local education record in `data.record`. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- Returns local subresource state.\n- No payer or school verification is performed.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means the education entry was not found through a session owned by the authenticated organization. Retry 5xx after reloading current record state.\n\n### Error notes\n- 400 can mean invalid date formatting.\n- 404 can mean missing, soft-deleted, or wrong-tenant record.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"educationId","in":"path","description":"QuickRCM Credentialing education record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"educationType":{"type":["string","null"],"maxLength":255,"description":"Education category or training type for the credentialing packet. Nullable and capped at 255 characters."},"degree":{"type":["string","null"],"maxLength":255,"description":"Degree or credential label for the education entry. Nullable and capped at 255 characters."},"institutionName":{"type":["string","null"],"maxLength":255,"description":"Institution name for the education entry. Nullable and capped at 255 characters."},"startDate":{"type":["string","null"],"minLength":1,"description":"Start date string for the education period. Null clears the value; invalid date strings return 400."},"endDate":{"type":["string","null"],"minLength":1,"description":"End date string for the education period. Use null for open or unknown dates when appropriate; invalid date strings return 400."}}},"example":{"educationType":"example-educationtype","degree":"example-degree","institutionName":"Example credentialing_education","startDate":"2026-06-08","endDate":"2026-06-08"}}},"description":"Send only the fields to update. Date fields are parsed and invalid dates return 400. This endpoint does not accept document uploads or external verification payloads."},"responses":{"200":{"description":"Education entry updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Education entry not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"delete":{"operationId":"deleteCredentialingEducation","summary":"Delete credentialing education entry","description":"Soft-deletes a local education history record after verifying tenant ownership through the parent Credentialing session.\n\n### When to use\nUse this endpoint to remove an education entry from active credentialing packet views without hard-deleting the record.\n\n### Before calling\nAuthenticate with `credentialing:write`. Use an `educationId` from the same organization.\n\n### Request guidance\nThe public body schema is empty. Pass the path `educationId` only and do not send tenant selectors or hard-delete flags.\n\n### Request notes\n- No request fields are required.\n- The operation is a soft delete.\n- Do not document a hard-delete option.\n\n### Response semantics\nA successful response returns `{ deleted: true, id }` and `meta.organizationId`. The handler marks `deletedAt` and `deletedBy`; it does not hard-delete the database row.\n\n### Response notes\n- `data.deleted` is true on success.\n- `data.id` echoes the deleted record identifier.\n- The record should disappear from non-deleted credentialing views.\n\n### Errors and retries\n404 means the record was missing, already not active, or not in the authenticated organization. Treat repeated deletes as non-idempotent unless the API later documents idempotent delete semantics.\n\n### Error notes\n- 404 can mean wrong organization.\n- Do not retry authorization failures unchanged.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"educationId","in":"path","description":"QuickRCM Credentialing education record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"The public body schema is empty. Pass the path `educationId` only and do not send tenant selectors or hard-delete flags."},"responses":{"200":{"description":"Education entry soft-deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"deleted":true,"id":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Education entry not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/work-history":{"post":{"operationId":"createCredentialingWorkHistory","summary":"Create credentialing work history entry","description":"Adds a work history record to an organization-scoped Credentialing session.\n\n### When to use\nUse this endpoint when assembling provider employment, practice, or role history for a credentialing packet.\n\n### Before calling\nAuthenticate with `credentialing:write` and confirm the session belongs to the API-key organization.\n\n### Request guidance\nSend structured work history metadata only. Date fields are parsed by the handler; invalid dates return 400. `practiceAddress` is capped at 2000 characters.\n\n### Request notes\n- Store structured metadata here, not supporting documents.\n- Use synthetic addresses in public examples.\n- The API key supplies tenant context.\n\n### Response semantics\nA 201 response returns the created local work history record in `data.record`. The endpoint does not contact employers or verify employment. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- `data.record` is local subresource state.\n- `sortOrder` is server-assigned.\n- No external verification is performed.\n\n### Errors and retries\n400 can indicate invalid dates or field limits. 404 means the session was not found in the authenticated organization. Check for duplicates before retrying an unknown create outcome.\n\n### Error notes\n- 400 can include invalid date parsing errors.\n- 404 can mean missing or wrong-tenant session.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"organizationName":{"type":["string","null"],"maxLength":255,"description":"Employer, practice, hospital, or organization name for the work history entry. Nullable and capped at 255 characters."},"role":{"type":["string","null"],"maxLength":255,"description":"Provider role or title for the work history period. Nullable and capped at 255 characters."},"startDate":{"type":["string","null"],"minLength":1,"description":"Start date string for the work history period. Null clears the value; invalid date strings return 400."},"endDate":{"type":["string","null"],"minLength":1,"description":"End date string for the work history period. Use null for current or unknown end dates when appropriate; invalid date strings return 400."},"practiceAddress":{"type":["string","null"],"maxLength":2000,"description":"Practice address for the work history entry. Nullable and capped at 2000 characters; treat as sensitive when linked to provider credentialing history."}}},"example":{"organizationName":"Example credentialing_work_history","role":"example-role","startDate":"2026-06-08","endDate":"2026-06-08","practiceAddress":"example-practiceaddress"}}},"description":"Send structured work history metadata only. Date fields are parsed by the handler; invalid dates return 400. `practiceAddress` is capped at 2000 characters."},"responses":{"201":{"description":"Work history entry created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/work-history/{workHistoryId}":{"put":{"operationId":"updateCredentialingWorkHistory","summary":"Update credentialing work history entry","description":"Updates a local work history record after verifying it belongs to a session in the API-key organization.\n\n### When to use\nUse this endpoint to correct provider employment or practice history already attached to a credentialing session.\n\n### Before calling\nAuthenticate with `credentialing:write`. Use a `workHistoryId` returned from the same tenant context.\n\n### Request guidance\nSend only fields to update. Date fields are parsed by the handler and `practiceAddress` remains capped at 2000 characters.\n\n### Request notes\n- `workHistoryId` is checked through nested organization ownership.\n- Use null to clear nullable fields.\n- Do not send credentialing documents in this request.\n\n### Response semantics\nA successful response returns the updated local work history record in `data.record`. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- Returns local subresource state.\n- No employer verification is performed.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means the work history record was not found through a session owned by the authenticated organization. Retry transient 5xx after reloading current record state.\n\n### Error notes\n- 400 can mean invalid dates.\n- 404 can mean missing, soft-deleted, or wrong-tenant record.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"workHistoryId","in":"path","description":"QuickRCM Credentialing work history record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"organizationName":{"type":["string","null"],"maxLength":255,"description":"Employer, practice, hospital, or organization name for the work history entry. Nullable and capped at 255 characters."},"role":{"type":["string","null"],"maxLength":255,"description":"Provider role or title for the work history period. Nullable and capped at 255 characters."},"startDate":{"type":["string","null"],"minLength":1,"description":"Start date string for the work history period. Null clears the value; invalid date strings return 400."},"endDate":{"type":["string","null"],"minLength":1,"description":"End date string for the work history period. Use null for current or unknown end dates when appropriate; invalid date strings return 400."},"practiceAddress":{"type":["string","null"],"maxLength":2000,"description":"Practice address for the work history entry. Nullable and capped at 2000 characters; treat as sensitive when linked to provider credentialing history."}}},"example":{"organizationName":"Example credentialing_work_history","role":"example-role","startDate":"2026-06-08","endDate":"2026-06-08","practiceAddress":"example-practiceaddress"}}},"description":"Send only fields to update. Date fields are parsed by the handler and `practiceAddress` remains capped at 2000 characters."},"responses":{"200":{"description":"Work history entry updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Work history entry not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"delete":{"operationId":"deleteCredentialingWorkHistory","summary":"Delete credentialing work history entry","description":"Soft-deletes a local work history record after verifying tenant ownership through the parent Credentialing session.\n\n### When to use\nUse this endpoint to remove an employment or practice history entry from active credentialing packet views.\n\n### Before calling\nAuthenticate with `credentialing:write` and use a work history ID from the same organization.\n\n### Request guidance\nThe public body schema is empty. Pass the path `workHistoryId` only.\n\n### Request notes\n- No request fields are required.\n- The operation is a soft delete.\n- No external employment system is contacted.\n\n### Response semantics\nA successful response returns `{ deleted: true, id }` and records a soft delete with `deletedAt` and `deletedBy` internally.\n\n### Response notes\n- `data.deleted` is true on success.\n- `data.id` echoes the deleted record ID.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means the record was not found, already not active, or not owned by the authenticated organization. Do not treat this as a hard-delete confirmation.\n\n### Error notes\n- 404 can mean wrong organization.\n- Do not retry malformed IDs unchanged.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"workHistoryId","in":"path","description":"QuickRCM Credentialing work history record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"The public body schema is empty. Pass the path `workHistoryId` only."},"responses":{"200":{"description":"Work history entry soft-deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"deleted":true,"id":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Work history entry not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/licenses":{"post":{"operationId":"createCredentialingLicense","summary":"Create credentialing license entry","description":"Adds a professional license identifier record to an organization-scoped Credentialing session.\n\n### When to use\nUse this endpoint to add state medical license, CDS, DEA-like, or other professional identifier metadata needed in a credentialing packet.\n\n### Before calling\nAuthenticate with `credentialing:write` and confirm the session belongs to the API-key organization.\n\n### Request guidance\nSend structured license metadata only. Date fields are parsed by the handler and invalid dates return 400. Do not send scanned license files here; use document workflows for file metadata.\n\n### Request notes\n- Use this for structured license metadata.\n- Supporting document files are separate.\n- Do not include payer portal credentials.\n\n### Response semantics\nA 201 response returns the created local license record in `data.record`. It does not perform primary source verification or query licensing boards. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- `data.record` is local subresource state.\n- No licensing-board verification is performed.\n- The record includes session ownership through `sessionId`.\n\n### Errors and retries\n400 can indicate invalid date or field bounds. 404 means the session was not found in the authenticated organization. Check for duplicates before retrying uncertain creates.\n\n### Error notes\n- 400 can mean invalid `issueDate` or `expirationDate`.\n- 404 can mean wrong-tenant session.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"professionalIdType":{"type":["string","null"],"maxLength":255,"description":"Type of provider professional identifier, such as a state medical license or controlled substance registration label. Nullable and capped at 255 characters."},"state":{"type":["string","null"],"maxLength":100,"description":"State, territory, or jurisdiction label for the professional identifier. Nullable and capped at 100 characters."},"professionalIdNumber":{"type":["string","null"],"maxLength":255,"description":"Provider professional identifier value. Nullable and capped at 255 characters; treat as sensitive provider credentialing data."},"issueDate":{"type":["string","null"],"minLength":1,"description":"Issue date string for the license or professional identifier. Null clears the value; invalid date strings return 400."},"expirationDate":{"type":["string","null"],"minLength":1,"description":"Expiration date string for the license or professional identifier. Null clears the value; invalid date strings return 400."}}},"example":{"professionalIdType":"example-professionalidtype","state":"example-state","professionalIdNumber":"example-professionalidnumber","issueDate":"2026-06-08","expirationDate":"2026-06-08"}}},"description":"Send structured license metadata only. Date fields are parsed by the handler and invalid dates return 400. Do not send scanned license files here; use document workflows for file metadata."},"responses":{"201":{"description":"License entry created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/licenses/{licenseId}":{"put":{"operationId":"updateCredentialingLicense","summary":"Update credentialing license entry","description":"Updates a professional license record after verifying it belongs to a session in the API-key organization.\n\n### When to use\nUse this endpoint to correct license type, state, identifier number, issue date, or expiration date.\n\n### Before calling\nAuthenticate with `credentialing:write`. Use a `licenseId` returned from the same tenant context.\n\n### Request guidance\nSend only fields to update. Date fields are parsed; invalid dates return 400. Do not send supporting image/PDF content in this request.\n\n### Request notes\n- `licenseId` is checked through nested organization ownership.\n- Use null to clear nullable fields when allowed.\n- This endpoint does not verify license status externally.\n\n### Response semantics\nA successful response returns the updated local license record in `data.record`. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- Returns local subresource state.\n- No primary source verification is performed.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means the license record was not found through a session owned by the authenticated organization. Retry transient 5xx after reloading current record state.\n\n### Error notes\n- 400 can mean invalid issue or expiration date.\n- 404 can mean missing, soft-deleted, or wrong-tenant record.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"licenseId","in":"path","description":"QuickRCM Credentialing license record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"professionalIdType":{"type":["string","null"],"maxLength":255,"description":"Type of provider professional identifier, such as a state medical license or controlled substance registration label. Nullable and capped at 255 characters."},"state":{"type":["string","null"],"maxLength":100,"description":"State, territory, or jurisdiction label for the professional identifier. Nullable and capped at 100 characters."},"professionalIdNumber":{"type":["string","null"],"maxLength":255,"description":"Provider professional identifier value. Nullable and capped at 255 characters; treat as sensitive provider credentialing data."},"issueDate":{"type":["string","null"],"minLength":1,"description":"Issue date string for the license or professional identifier. Null clears the value; invalid date strings return 400."},"expirationDate":{"type":["string","null"],"minLength":1,"description":"Expiration date string for the license or professional identifier. Null clears the value; invalid date strings return 400."}}},"example":{"professionalIdType":"example-professionalidtype","state":"example-state","professionalIdNumber":"example-professionalidnumber","issueDate":"2026-06-08","expirationDate":"2026-06-08"}}},"description":"Send only fields to update. Date fields are parsed; invalid dates return 400. Do not send supporting image/PDF content in this request."},"responses":{"200":{"description":"License entry updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"License entry not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"delete":{"operationId":"deleteCredentialingLicense","summary":"Delete credentialing license entry","description":"Soft-deletes a local professional license record after verifying tenant ownership through the parent Credentialing session.\n\n### When to use\nUse this endpoint to remove a license entry from active credentialing packet views.\n\n### Before calling\nAuthenticate with `credentialing:write` and use a license ID from the same organization.\n\n### Request guidance\nThe public body schema is empty. Pass only the path `licenseId`.\n\n### Request notes\n- No request fields are required.\n- The operation is a soft delete.\n- No licensing-board or payer system is contacted.\n\n### Response semantics\nA successful response returns `{ deleted: true, id }` and internally sets soft-delete metadata.\n\n### Response notes\n- `data.deleted` is true on success.\n- `data.id` echoes the deleted record ID.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means missing, already inactive, or wrong-organization license context. Do not describe this as hard deletion.\n\n### Error notes\n- 404 can mean wrong organization.\n- Do not retry malformed IDs unchanged.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"licenseId","in":"path","description":"QuickRCM Credentialing license record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"The public body schema is empty. Pass only the path `licenseId`."},"responses":{"200":{"description":"License entry soft-deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"deleted":true,"id":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"License entry not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/references":{"post":{"operationId":"createCredentialingProfessionalReference","summary":"Create credentialing professional reference","description":"Adds a professional reference record to an organization-scoped Credentialing session.\n\n### When to use\nUse this endpoint to capture reference contact metadata needed for a provider credentialing packet.\n\n### Before calling\nAuthenticate with `credentialing:write` and confirm the session exists in the API-key organization.\n\n### Request guidance\nSend structured reference metadata only. `email` must be a valid email when provided. Avoid storing unnecessary personal details beyond the credentialing workflow need.\n\n### Request notes\n- Use this for reference contact metadata only.\n- Do not include credentials or unrelated personal information.\n- The API key supplies tenant context.\n\n### Response semantics\nA 201 response returns the created local professional reference record in `data.record`. The endpoint does not contact the reference. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- `data.record` is local subresource state.\n- No outbound reference contact occurs.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n400 can indicate invalid email or field bounds. 404 means the session was not found in the authenticated organization. Check for duplicates before retrying uncertain creates.\n\n### Error notes\n- 400 can mean invalid email formatting.\n- 404 can mean missing or wrong-tenant session.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":255,"description":"Professional reference contact name. Nullable and capped at 255 characters; use synthetic examples in public docs."},"position":{"type":["string","null"],"maxLength":255,"description":"Professional title or role for the reference contact. Nullable and capped at 255 characters."},"practiceName":{"type":["string","null"],"maxLength":255,"description":"Practice or organization associated with the professional reference. Nullable and capped at 255 characters."},"phone":{"type":["string","null"],"maxLength":50,"description":"Professional reference phone number. Nullable and capped at 50 characters."},"email":{"type":["string","null"],"maxLength":255,"format":"email","description":"Professional reference email address. Nullable, capped at 255 characters, and must be valid email syntax when provided."},"relationship":{"type":["string","null"],"maxLength":255,"description":"Credentialing relationship context between the provider and reference. Nullable and capped at 255 characters."}}},"example":{"name":"Example credentialing_professional_reference","position":"example-position","practiceName":"Example credentialing_professional_reference","phone":"+15551234567","email":"developer@example.com","relationship":"example-relationship"}}},"description":"Send structured reference metadata only. `email` must be a valid email when provided. Avoid storing unnecessary personal details beyond the credentialing workflow need."},"responses":{"201":{"description":"Professional reference created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/references/{referenceId}":{"put":{"operationId":"updateCredentialingProfessionalReference","summary":"Update credentialing professional reference","description":"Updates a professional reference record after verifying it belongs to a session in the API-key organization.\n\n### When to use\nUse this endpoint to correct reference contact details or relationship metadata.\n\n### Before calling\nAuthenticate with `credentialing:write`. Use a `referenceId` returned from the same tenant context.\n\n### Request guidance\nSend only fields to update. `email` must be valid when present. Keep reference notes and credentials out of this structured metadata request.\n\n### Request notes\n- `referenceId` is checked through nested organization ownership.\n- Use null to clear nullable fields when allowed.\n- The endpoint does not send email or call the reference.\n\n### Response semantics\nA successful response returns the updated local professional reference record in `data.record`. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- Returns local subresource state.\n- No outbound communication is performed.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means the reference was not found through a session owned by the authenticated organization. Retry transient 5xx after checking current record state.\n\n### Error notes\n- 400 can mean invalid email formatting.\n- 404 can mean missing, soft-deleted, or wrong-tenant record.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"referenceId","in":"path","description":"QuickRCM Credentialing professional reference record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":255,"description":"Professional reference contact name. Nullable and capped at 255 characters; use synthetic examples in public docs."},"position":{"type":["string","null"],"maxLength":255,"description":"Professional title or role for the reference contact. Nullable and capped at 255 characters."},"practiceName":{"type":["string","null"],"maxLength":255,"description":"Practice or organization associated with the professional reference. Nullable and capped at 255 characters."},"phone":{"type":["string","null"],"maxLength":50,"description":"Professional reference phone number. Nullable and capped at 50 characters."},"email":{"type":["string","null"],"maxLength":255,"format":"email","description":"Professional reference email address. Nullable, capped at 255 characters, and must be valid email syntax when provided."},"relationship":{"type":["string","null"],"maxLength":255,"description":"Credentialing relationship context between the provider and reference. Nullable and capped at 255 characters."}}},"example":{"name":"Example credentialing_professional_reference","position":"example-position","practiceName":"Example credentialing_professional_reference","phone":"+15551234567","email":"developer@example.com","relationship":"example-relationship"}}},"description":"Send only fields to update. `email` must be valid when present. Keep reference notes and credentials out of this structured metadata request."},"responses":{"200":{"description":"Professional reference updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Professional reference not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"delete":{"operationId":"deleteCredentialingProfessionalReference","summary":"Delete credentialing professional reference","description":"Soft-deletes a professional reference record after verifying tenant ownership through the parent Credentialing session.\n\n### When to use\nUse this endpoint to remove a reference entry from active credentialing packet views.\n\n### Before calling\nAuthenticate with `credentialing:write` and use a reference ID from the same organization.\n\n### Request guidance\nThe public body schema is empty. Pass only the path `referenceId`.\n\n### Request notes\n- No request fields are required.\n- The operation is a soft delete.\n- No external contact is made.\n\n### Response semantics\nA successful response returns `{ deleted: true, id }` and internally sets soft-delete metadata.\n\n### Response notes\n- `data.deleted` is true on success.\n- `data.id` echoes the deleted record ID.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means missing, already inactive, or wrong-organization reference context. Do not describe this as hard deletion.\n\n### Error notes\n- 404 can mean wrong organization.\n- Do not retry malformed IDs unchanged.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"referenceId","in":"path","description":"QuickRCM Credentialing professional reference record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"The public body schema is empty. Pass only the path `referenceId`."},"responses":{"200":{"description":"Professional reference soft-deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"deleted":true,"id":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Professional reference not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/liability-insurance":{"post":{"operationId":"createCredentialingLiabilityInsurance","summary":"Create credentialing liability insurance","description":"Adds liability insurance coverage metadata to an organization-scoped Credentialing session.\n\n### When to use\nUse this endpoint to capture malpractice or liability insurance details required for a credentialing packet.\n\n### Before calling\nAuthenticate with `credentialing:write` and confirm the session belongs to the API-key organization.\n\n### Request guidance\nSend structured insurance metadata only. Date fields are parsed by the handler; invalid dates return 400. Do not send policy documents or payment credentials here.\n\n### Request notes\n- Use this for structured coverage metadata.\n- Supporting policy documents belong in document workflows.\n- Policy numbers are sensitive provider credentialing data.\n\n### Response semantics\nA 201 response returns the created local liability insurance record in `data.record`. The endpoint does not verify coverage with carriers. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- `data.record` is local subresource state.\n- No insurance carrier verification is performed.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n400 can indicate invalid dates or field bounds. 404 means the session was not found in the authenticated organization. Check for duplicates before retrying uncertain creates.\n\n### Error notes\n- 400 can mean invalid effective or expiration date.\n- 404 can mean missing or wrong-tenant session.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"issuedBy":{"type":["string","null"],"maxLength":255,"description":"Liability or malpractice insurance carrier name. Nullable and capped at 255 characters."},"policyNumber":{"type":["string","null"],"maxLength":255,"description":"Liability insurance policy number. Nullable and capped at 255 characters; treat as sensitive credentialing and financial context."},"policyLimits":{"type":["string","null"],"maxLength":255,"description":"Coverage limit text for the policy, such as per-claim and aggregate limits. Nullable and capped at 255 characters."},"coverageType":{"type":["string","null"],"maxLength":255,"description":"Coverage category or policy type for liability insurance. Nullable and capped at 255 characters."},"effectiveDate":{"type":["string","null"],"minLength":1,"description":"Effective date string for liability insurance coverage. Null clears the value; invalid date strings return 400."},"expirationDate":{"type":["string","null"],"minLength":1,"description":"Expiration date string for liability insurance coverage. Null clears the value; invalid date strings return 400."}}},"example":{"issuedBy":"example-issuedby","policyNumber":"example-policynumber","policyLimits":"example-policylimits","coverageType":"example-coveragetype","effectiveDate":"2026-06-08","expirationDate":"2026-06-08"}}},"description":"Send structured insurance metadata only. Date fields are parsed by the handler; invalid dates return 400. Do not send policy documents or payment credentials here."},"responses":{"201":{"description":"Liability insurance entry created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/liability-insurance/{insuranceId}":{"put":{"operationId":"updateCredentialingLiabilityInsurance","summary":"Update credentialing liability insurance","description":"Updates liability insurance coverage metadata after verifying it belongs to a session in the API-key organization.\n\n### When to use\nUse this endpoint to correct carrier, policy number, limits, coverage type, or coverage dates.\n\n### Before calling\nAuthenticate with `credentialing:write`. Use an `insuranceId` returned from the same tenant context.\n\n### Request guidance\nSend only fields to update. Date fields are parsed by the handler; invalid dates return 400. Do not send policy document files in this request.\n\n### Request notes\n- `insuranceId` is checked through nested organization ownership.\n- Use null to clear nullable fields when allowed.\n- The endpoint does not verify coverage externally.\n\n### Response semantics\nA successful response returns the updated local liability insurance record in `data.record`. The `data.record` object is a passthrough public subresource record: it always includes normalized `id`, `sessionId`, `sortOrder`, `deletedAt`, `createdAt`, and `updatedAt`, plus the accepted fields for that subresource.\n\n### Response notes\n- Returns local subresource state.\n- No carrier verification is performed.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means the insurance record was not found through a session owned by the authenticated organization. Retry transient 5xx after reloading current record state.\n\n### Error notes\n- 400 can mean invalid effective or expiration date.\n- 404 can mean missing, soft-deleted, or wrong-tenant record.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"insuranceId","in":"path","description":"QuickRCM Credentialing liability insurance record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"issuedBy":{"type":["string","null"],"maxLength":255,"description":"Liability or malpractice insurance carrier name. Nullable and capped at 255 characters."},"policyNumber":{"type":["string","null"],"maxLength":255,"description":"Liability insurance policy number. Nullable and capped at 255 characters; treat as sensitive credentialing and financial context."},"policyLimits":{"type":["string","null"],"maxLength":255,"description":"Coverage limit text for the policy, such as per-claim and aggregate limits. Nullable and capped at 255 characters."},"coverageType":{"type":["string","null"],"maxLength":255,"description":"Coverage category or policy type for liability insurance. Nullable and capped at 255 characters."},"effectiveDate":{"type":["string","null"],"minLength":1,"description":"Effective date string for liability insurance coverage. Null clears the value; invalid date strings return 400."},"expirationDate":{"type":["string","null"],"minLength":1,"description":"Expiration date string for liability insurance coverage. Null clears the value; invalid date strings return 400."}}},"example":{"issuedBy":"example-issuedby","policyNumber":"example-policynumber","policyLimits":"example-policylimits","coverageType":"example-coveragetype","effectiveDate":"2026-06-08","expirationDate":"2026-06-08"}}},"description":"Send only fields to update. Date fields are parsed by the handler; invalid dates return 400. Do not send policy document files in this request."},"responses":{"200":{"description":"Liability insurance entry updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"sortOrder":{"type":"integer"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","sessionId","sortOrder","deletedAt","createdAt","updatedAt"]}},"required":["record"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"record":{"id":"00000000-0000-4000-8000-000000000001","sessionId":"00000000-0000-4000-8000-000000000001","sortOrder":1,"deletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Liability insurance entry not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"delete":{"operationId":"deleteCredentialingLiabilityInsurance","summary":"Delete credentialing liability insurance","description":"Soft-deletes liability insurance coverage metadata after verifying tenant ownership through the parent Credentialing session.\n\n### When to use\nUse this endpoint to remove a liability insurance entry from active credentialing packet views.\n\n### Before calling\nAuthenticate with `credentialing:write` and use an insurance ID from the same organization.\n\n### Request guidance\nThe public body schema is empty. Pass only the path `insuranceId`.\n\n### Request notes\n- No request fields are required.\n- The operation is a soft delete.\n- No carrier or payer system is contacted.\n\n### Response semantics\nA successful response returns `{ deleted: true, id }` and internally sets soft-delete metadata.\n\n### Response notes\n- `data.deleted` is true on success.\n- `data.id` echoes the deleted record ID.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means missing, already inactive, or wrong-organization insurance context. Do not describe this as hard deletion.\n\n### Error notes\n- 404 can mean wrong organization.\n- Do not retry malformed IDs unchanged.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"insuranceId","in":"path","description":"QuickRCM Credentialing liability insurance record identifier. It must resolve through a session owned by the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"The public body schema is empty. Pass only the path `insuranceId`."},"responses":{"200":{"description":"Liability insurance entry soft-deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"id":{"type":"string"}},"required":["deleted","id"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"deleted":true,"id":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Liability insurance entry not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/signature":{"put":{"operationId":"saveCredentialingSignature","summary":"Save credentialing signature reference","description":"Links an existing organization-owned QuickRCM File record as the signature reference for a Credentialing session.\n\n### When to use\nUse this endpoint after a signature file already exists in QuickRCM and the credentialing packet needs to reference it before application readiness validation.\n\n### Before calling\nAuthenticate with `credentialing:write`. Confirm both the session and the signature File record belong to the API-key organization.\n\n### Request guidance\nSend `signatureFileId` only. The public API does not accept raw signature image data, base64 image payloads, S3 keys, or presigned URLs in this request.\n\n### Request notes\n- `signatureFileId` must reference an existing organization-owned File.\n- Do not send raw image data.\n- Do not expose storage keys or signed URLs in docs examples.\n\n### Response semantics\nA successful response returns the session ID and linked signature File ID. It updates the local session signature reference and does not upload or transform the file.\n\n### Response notes\n- Returns `sessionId` and `signatureFileId` only.\n- The response includes `meta.organizationId`.\n\n### Errors and retries\n404 means either the session or signature file was not found in the authenticated organization. Retry transient 5xx after checking current session state.\n\n### Error notes\n- 404 can mean the File belongs to another organization.\n- 400 can mean the required signatureFileId is missing.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signatureFileId":{"type":"string","minLength":1,"description":"Existing QuickRCM File identifier owned by the API-key organization. Required body field; public Credentialing API calls do not accept raw signature image data, base64, S3 keys, or presigned URLs."}},"required":["signatureFileId"]},"example":{"signatureFileId":"00000000-0000-4000-8000-000000000001"}}},"description":"Send `signatureFileId` only. The public API does not accept raw signature image data, base64 image payloads, S3 keys, or presigned URLs in this request."},"responses":{"200":{"description":"Signature file reference saved.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"sessionId":{"type":"string"},"signatureFileId":{"type":"string"}},"required":["sessionId","signatureFileId"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"sessionId":"00000000-0000-4000-8000-000000000001","signatureFileId":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session or signature file not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/attest":{"post":{"operationId":"acceptCredentialingAttestation","summary":"Accept credentialing attestation","description":"Records whether the credentialing attestation has been accepted for an organization-scoped session.\n\n### When to use\nUse this endpoint after the provider or authorized workflow has accepted or revoked attestation acceptance before application readiness validation.\n\n### Before calling\nAuthenticate with `credentialing:write` and confirm the session belongs to the API-key organization.\n\n### Request guidance\nSend the required boolean `accepted`. True records attestation acceptance metadata; false clears acceptance metadata in the handler.\n\n### Request notes\n- This endpoint does not submit to payer portals.\n- The API key supplies tenant context.\n\n### Response semantics\nA successful response returns `sessionId` and `accepted`. It updates local attestation state only and does not submit the application.\n\n### Response notes\n- Returns only the session ID and accepted flag.\n- Acceptance timestamp and actor are not exposed in the response schema.\n- Application readiness is checked later by submitCredentialingApplication.\n\n### Errors and retries\n400 means the boolean was missing or invalid. 404 means the session was not found in the authenticated organization. Retry transient failures after reloading current attestation state.\n\n### Error notes\n- 404 can mean wrong-tenant session.\n- Do not retry malformed boolean payloads unchanged.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","description":"Required boolean. True records local attestation acceptance metadata; false clears local acceptance metadata."}},"required":["accepted"]},"example":{"accepted":true}}},"description":"Send the required boolean `accepted`. True records attestation acceptance metadata; false clears acceptance metadata in the handler."},"responses":{"200":{"description":"Attestation acceptance updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"sessionId":{"type":"string"},"accepted":{"type":"boolean"}},"required":["sessionId","accepted"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"sessionId":"00000000-0000-4000-8000-000000000001","accepted":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/submit":{"post":{"operationId":"submitCredentialingApplication","summary":"Queue credentialing application submit","description":"Validates Credentialing application readiness and returns a safe workflow response without payer portal submission.\n\n### When to use\nUse this endpoint after provider info, signature reference, attestation, payer selections, and required classified documents are present and you want a public API readiness check or simulated queue response.\n\n### Before calling\nAuthenticate with `credentialing:write`. The session must be IN_PROGRESS, have provider firstName, lastName, and NPI, have a signature File reference, accepted attestation, at least one selected payer, and classified CV, DEA_CERTIFICATE, STATE_CDS_CERTIFICATE, BOARD_CERTIFICATION, and MALPRACTICE_INSURANCE document types.\n\n### Request guidance\n`queueOnly` defaults to true and `validateOnly` defaults to false. At least one of `queueOnly` or `validateOnly` must be true; `queueOnly: false` is accepted only when `validateOnly: true`. `idempotencyKey` is accepted as a schema field, but current simulation handling does not persist de-duplication state.\n\n### Request notes\n- Use `validateOnly: true` to check readiness without simulated queue messaging.\n- Required classified document types are CV, DEA_CERTIFICATE, STATE_CDS_CERTIFICATE, BOARD_CERTIFICATION, and MALPRACTICE_INSURANCE.\n- Do not document this endpoint as a live payer portal submission.\n\n### Response semantics\nA 202 response returns `status: VALIDATED_ONLY` when `validateOnly` is true, otherwise `status: SIMULATED_ONLY`, with `workflow: APPLICATION_SUBMIT`. The endpoint does not submit to payer portals, does not move session status, and does not create external confirmation evidence. Workflow responses use `data.status`, `data.workflow`, `data.message`, and the relevant `sessionId` or `documentId` identifier.\n\n### Response notes\n- 202 is a safe local workflow response, not payer submission evidence.\n- `VALIDATED_ONLY` is returned when `validateOnly` is true; otherwise the accepted public path returns `SIMULATED_ONLY`.\n- No local session status transition is performed by this public handler.\n\n### Errors and retries\n400 can indicate missing readiness prerequisites, invalid dates or body fields, or both `queueOnly` and `validateOnly` set to false. 404 means the session was not found in the API-key organization. Back off on 429.\n\n### Error notes\n- 400 can name missing signature, attestation, provider fields, selected payers, required document types, or invalid session status.\n- Do not retry readiness errors until the missing local session data has been corrected.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Safe-action flag for simulated public Credentialing submit workflow. Defaults to true; false is accepted only when validateOnly is true."},"validateOnly":{"type":"boolean","default":false,"description":"When true, validates application readiness and returns VALIDATED_ONLY without submit side effects. Takes precedence over queue simulation."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker capped at 128 characters. Do not include sensitive data; current public simulation handling does not persist de-duplication state."}}},"example":{"queueOnly":true,"validateOnly":false,"idempotencyKey":"example-idempotencykey"}}},"description":"`queueOnly` defaults to true and `validateOnly` defaults to false. At least one of `queueOnly` or `validateOnly` must be true; `queueOnly: false` is accepted only when `validateOnly: true`. `idempotencyKey` is accepted as a schema field, but current simulation handling does not persist de-duplication state."},"responses":{"202":{"description":"Submit request accepted as a simulated queue-only workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","SIMULATED_ONLY","VALIDATED_ONLY"]},"workflow":{"type":"string"},"sessionId":{"type":"string"},"documentId":{"type":"string"},"message":{"type":"string"}},"required":["status","workflow","message"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"status":"SAFE_WRITE_DB_ONLY","workflow":"example-workflow","message":"Request failed","sessionId":"00000000-0000-4000-8000-000000000001","documentId":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/credentialing/sessions/{sessionId}/status":{"put":{"operationId":"updateCredentialingSessionStatus","summary":"Update credentialing session status","description":"Updates the local status of a tenant-owned Credentialing session after validating the transition against the shared credentialing status machine.\n\n### When to use\nUse this v1 endpoint for new integrations that need to move a credentialing session through local workflow states.\n\n### Before calling\nAuthenticate with `credentialing:write`. Load the current session status first if your integration needs to avoid invalid transitions.\n\n### Request guidance\n`status` must be one of the public enum values and the transition from the current status must be allowed. `statusNotes` can be null or omitted and is capped at 2000 characters. Prefer this endpoint over the legacy callback.\n\n### Request notes\n- Use the canonical enum value exactly as documented.\n- Allowed transitions: DRAFT -> IN_PROGRESS; IN_PROGRESS -> SUBMITTED, DRAFT, ON_HOLD; SUBMITTED -> IN_REVIEW, FAILED, ON_HOLD; IN_REVIEW -> ACCEPTED, DENIED, FAILED, ON_HOLD; ACCEPTED -> COMPLETED, REVOKED, ON_HOLD; COMPLETED -> EXPIRED; FAILED -> DRAFT; DENIED -> DRAFT; ON_HOLD -> IN_PROGRESS, DRAFT; EXPIRED and REVOKED have no next states.\n- Use `statusNotes` for short internal workflow context only.\n\n### Response semantics\nA successful response returns the updated local session summary. The endpoint changes local QuickRCM status only; it does not submit applications, notify payers, or generate portal confirmations.\n\n### Response notes\n- Returns the updated local session summary.\n- No external payer or portal action occurs.\n- The response includes `meta.organizationId`.\n- Returned providerInfo, createdByUser, selectedPayers, and documentCount are current summary state after the status update, not fields written by the status request.\n\n### Errors and retries\n400 can indicate an invalid status value or invalid transition and may include allowed next statuses. 404 means the session was not found in the authenticated organization. Retry 5xx after reloading current status to avoid stale transitions.\n\n### Error notes\n- 400 invalid transition errors should be resolved by reloading current status and choosing an allowed next state.\n- 403 means the key lacks Credentialing write access.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"QuickRCM Credentialing session identifier in the path. It must belong to the organization selected by the bearer API key; wrong-tenant IDs resolve as authorization/not-found failures."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["DRAFT","IN_PROGRESS","SUBMITTED","IN_REVIEW","ACCEPTED","COMPLETED","FAILED","DENIED","EXPIRED","ON_HOLD","REVOKED"],"description":"Target local Credentialing session status. Valid transitions are enforced from the current session status. Allowed transitions: DRAFT -> IN_PROGRESS; IN_PROGRESS -> SUBMITTED, DRAFT, ON_HOLD; SUBMITTED -> IN_REVIEW, FAILED, ON_HOLD; IN_REVIEW -> ACCEPTED, DENIED, FAILED, ON_HOLD; ACCEPTED -> COMPLETED, REVOKED, ON_HOLD; COMPLETED -> EXPIRED; FAILED -> DRAFT; DENIED -> DRAFT; ON_HOLD -> IN_PROGRESS, DRAFT; EXPIRED and REVOKED have no next states."},"statusNotes":{"type":["string","null"],"maxLength":2000,"description":"Optional internal note associated with the status update. Nullable, capped at 2000 characters, and should not contain secrets."}},"required":["status"]},"example":{"status":"DRAFT","statusNotes":"Example credentialing_session_statu note"}}},"description":"`status` must be one of the public enum values and the transition from the current status must be allowed. `statusNotes` can be null or omitted and is capped at 2000 characters. Prefer this endpoint over the legacy callback."},"responses":{"200":{"description":"Credentialing session status updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","IN_PROGRESS","SUBMITTED","IN_REVIEW","ACCEPTED","COMPLETED","FAILED","DENIED","EXPIRED","ON_HOLD","REVOKED"]},"statusNotes":{"type":["string","null"]},"providerName":{"type":["string","null"]},"providerInfo":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"npi":{"type":["string","null"]},"title":{"type":["string","null"]},"specialties":{"type":"array","items":{"type":"string"}},"languagesSpoken":{"type":"array","items":{"type":"string"}}},"required":["id","firstName","middleName","lastName","npi","title","specialties","languagesSpoken"]},"createdByUser":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"selectedPayers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["id","payerId","payerName"]}},"required":["id","payerConfigId","payerConfig"]}},"documentCount":{"type":"integer","minimum":0},"attestationAccepted":{"type":"boolean"},"submittedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","status","statusNotes","providerName","providerInfo","createdByUser","selectedPayers","documentCount","attestationAccepted","submittedAt","createdAt","updatedAt"]}},"required":["session"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"session":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","statusNotes":"Example credentialing_session_statu note","providerName":"Example credentialing_session_statu","providerInfo":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","middleName":"Example credentialing_session_statu","lastName":"Smith","npi":"1234567893","title":"Example credentialing_session_statu","specialties":["example-specialties"],"languagesSpoken":["example-languagesspoken"]},"createdByUser":{"id":"00000000-0000-4000-8000-000000000001","name":"Example credentialing_session_statu"},"selectedPayers":[{"id":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","payerName":"Example credentialing_session_statu"}}],"documentCount":1,"attestationAccepted":true,"submittedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/credentialing/update-status":{"post":{"operationId":"legacyUpdateCredentialingStatus","summary":"Legacy update credentialing status callback","description":"Provides a deprecated compatibility callback for updating a local Credentialing session status through the public API authentication path.\n\n### When to use\nUse only for legacy integrations that cannot yet call `PUT /api/v1/credentialing/sessions/{sessionId}/status`. New integrations should use the v1 status endpoint.\n\n### Before calling\nAuthenticate with `credentialing:write`. This legacy endpoint accepts `Authorization: Bearer` and also supports `x-api-key` compatibility when no Authorization header is present.\n\n### Request guidance\nSend `sessionId`, `status`, and optional `notes`. The handler normalizes status text to uppercase underscore form and validates the same status transitions. Do not send `orgId` or `organizationId` in the public body.\n\n### Request notes\n- Prefer the v1 status endpoint for new callers.\n- `x-api-key` compatibility is supported only for this legacy callback path when Authorization is absent; new examples should use Authorization: Bearer.\n- Allowed transitions: DRAFT -> IN_PROGRESS; IN_PROGRESS -> SUBMITTED, DRAFT, ON_HOLD; SUBMITTED -> IN_REVIEW, FAILED, ON_HOLD; IN_REVIEW -> ACCEPTED, DENIED, FAILED, ON_HOLD; ACCEPTED -> COMPLETED, REVOKED, ON_HOLD; COMPLETED -> EXPIRED; FAILED -> DRAFT; DENIED -> DRAFT; ON_HOLD -> IN_PROGRESS, DRAFT; EXPIRED and REVOKED have no next states.\n- Do not include public tenant selectors in the body.\n\n### Response semantics\nA successful response returns `success`, message, top-level `sessionId` and `status`, the same values under `data`, and `meta.organizationId`. It updates local status notes from `notes` when provided.\n\n### Response notes\n- Returns local status update confirmation.\n- No external payer or portal action occurs.\n- The endpoint is deprecated compatibility surface.\n\n### Errors and retries\n400 can indicate an invalid status value or invalid transition. 401/403 indicate missing key or write scope. 404 means the session was not found in the API-key organization. Prefer migrating callers instead of expanding this legacy contract.\n\n### Error notes\n- 400 invalid transition errors require reloading current status and choosing an allowed next state.\n- 403 means the key lacks Credentialing write access.\n","tags":["Credentialing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1,"description":"QuickRCM Credentialing session identifier in the legacy body. It must belong to the organization selected by the API key; do not send orgId or organizationId."},"status":{"type":"string","minLength":1,"description":"Target local Credentialing session status. The legacy handler normalizes text before validating enum value and allowed transition. Allowed transitions: DRAFT -> IN_PROGRESS; IN_PROGRESS -> SUBMITTED, DRAFT, ON_HOLD; SUBMITTED -> IN_REVIEW, FAILED, ON_HOLD; IN_REVIEW -> ACCEPTED, DENIED, FAILED, ON_HOLD; ACCEPTED -> COMPLETED, REVOKED, ON_HOLD; COMPLETED -> EXPIRED; FAILED -> DRAFT; DENIED -> DRAFT; ON_HOLD -> IN_PROGRESS, DRAFT; EXPIRED and REVOKED have no next states."},"notes":{"type":["string","null"],"maxLength":2000,"description":"Optional legacy status note that maps to the session local statusNotes field. Nullable, capped at 2000 characters, and should not contain secrets."}},"required":["sessionId","status"]},"example":{"sessionId":"00000000-0000-4000-8000-000000000001","status":"active","notes":"Example legacy_update_credentialing_statu note"}}},"description":"Send `sessionId`, `status`, and optional `notes`. The handler normalizes status text to uppercase underscore form and validates the same status transitions. Do not send `orgId` or `organizationId` in the public body."},"responses":{"200":{"description":"Legacy credentialing status callback accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"},"sessionId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","IN_PROGRESS","SUBMITTED","IN_REVIEW","ACCEPTED","COMPLETED","FAILED","DENIED","EXPIRED","ON_HOLD","REVOKED"]},"data":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","IN_PROGRESS","SUBMITTED","IN_REVIEW","ACCEPTED","COMPLETED","FAILED","DENIED","EXPIRED","ON_HOLD","REVOKED"]}},"required":["sessionId","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","message","sessionId","status","data","meta"]},"example":{"success":true,"message":"Request failed","sessionId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","data":{"sessionId":"00000000-0000-4000-8000-000000000001","status":"DRAFT"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/denial-management/cases":{"get":{"operationId":"listDenialCases","summary":"List denial cases","description":"Lists denial cases owned by the organization selected by the bearer API key, with optional filters for local status, denial category, severity, payer, claim, patient, queue, owner user, and pagination.\n\n### When to use\nUse this endpoint to build denial worklists, queue dashboards, aging reviews, appeal-prep picklists, or integration reconciliation screens that need a bounded set of local denial cases.\n\n### Before calling\nAuthenticate with an API key that has `denial-management:read` or `denial-management:write`. Decide which operational filters should narrow the list and use skip/take pagination on every production call.\n\n### Request guidance\n`skip` defaults to 0 and is capped at 10000. `take` defaults to 25 and is capped at 100. The API key selects the tenant; do not send `organizationId`. Treat patient, payer, claim, queue, and owner identifiers as QuickRCM-local selectors that still remain organization-scoped.\n\n### Request notes\n- Use `status`, `category`, `severity`, `payerId`, `claimId`, `patientId`, `queueId`, or `ownerUserId` to avoid broad denial exports.\n- The endpoint orders cases by `updatedAt` descending in the current handler.\n- Filter values can reveal patient or denial workflow context, so avoid logging raw query strings.\n\n### Response semantics\nThe response contains local QuickRCM denial case summaries, total count, and the effective pagination values. Each case includes monetary strings, status, root-cause fields, Claim Adjustment Reason Code (CARC) and Remittance Advice Remark Code (RARC) summaries, SLA and appeal deadline timestamps, limited claim/patient/facility/queue/payer summaries, and related-count totals. It is not payer adjudication evidence and does not include raw payer payloads or full patient demographics.\n\n### Response notes\n- `data.denialCases` is local denial workflow state, not a payer response or appeal outcome.\n- Nested `patient` is a limited display summary; raw demographics such as MRN are not part of the public response.\n- `counts` reports related local appeals, activities, files, and lines for workflow navigation.\n\n### Errors and retries\nTreat 400 as invalid filters or pagination bounds, 401 as missing or invalid bearer credentials, 403 as missing Denial Management scope or organization access, and 429 as a backoff signal. Retry only transient 5xx or rate-limit responses with bounded backoff.\n\n### Error notes\n- 400 can indicate an unsupported enum value or out-of-range pagination.\n- 403 means the API key lacks Denial Management access even if it has other module scopes.\n- 429 should be retried with backoff rather than tight polling.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["NEW","IN_PROGRESS","ON_HOLD","RESUBMITTED","APPEALED","CLOSED_PAID","CLOSED_PARTIAL","CLOSED_WRITE_OFF","CLOSED_DROPPED"]},"required":false,"name":"status","in":"query","description":"Optional local denial case status filter. The public enum includes NEW, IN_PROGRESS, ON_HOLD, RESUBMITTED, APPEALED, CLOSED_PAID, CLOSED_PARTIAL, CLOSED_WRITE_OFF, and CLOSED_DROPPED."},{"schema":{"type":"string","enum":["ELIGIBILITY","AUTHORIZATION","CODING","MEDICAL_NECESSITY","TIMELY_FILING","COB","BENEFIT_EXHAUSTED","DUPLICATE","BUNDLING","OTHER"]},"required":false,"name":"category","in":"query","description":"Optional denial category filter such as ELIGIBILITY, AUTHORIZATION, CODING, MEDICAL_NECESSITY, TIMELY_FILING, COB, BENEFIT_EXHAUSTED, DUPLICATE, BUNDLING, or OTHER."},{"schema":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"required":false,"name":"severity","in":"query","description":"Optional denial severity filter. Valid values are LOW, MEDIUM, HIGH, and CRITICAL."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"payerId","in":"query","description":"Optional payer identifier filter stored on the denial case. It must be interpreted within the authenticated organization context."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"claimId","in":"query","description":"Optional QuickRCM claim identifier filter. The claim relationship remains organization-scoped."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"patientId","in":"query","description":"Optional QuickRCM patient identifier filter. Avoid logging raw values."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"queueId","in":"query","description":"Optional Denial Management queue identifier filter for the authenticated organization."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"ownerUserId","in":"query","description":"Optional QuickRCM user identifier filter for the case owner inside the authenticated organization."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"skip","in":"query","description":"Zero-based number of denial cases to skip. Defaults to 0 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"take","in":"query","description":"Maximum denial cases to return. Defaults to 25 and cannot exceed 100."}],"responses":{"200":{"description":"Denial case list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"denialCases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"facilityId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"claimId":{"type":["string","null"]},"patientId":{"type":["string","null"]},"payerId":{"type":"string"},"category":{"type":"string","enum":["ELIGIBILITY","AUTHORIZATION","CODING","MEDICAL_NECESSITY","TIMELY_FILING","COB","BENEFIT_EXHAUSTED","DUPLICATE","BUNDLING","OTHER"]},"rootCauseCode":{"type":["string","null"]},"rootCauseLabel":{"type":["string","null"]},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"deniedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"expectedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"paidAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"status":{"type":"string","enum":["NEW","IN_PROGRESS","ON_HOLD","RESUBMITTED","APPEALED","CLOSED_PAID","CLOSED_PARTIAL","CLOSED_WRITE_OFF","CLOSED_DROPPED"]},"openedAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"appealDeadline":{"type":["string","null"],"format":"date-time"},"slaDueAt":{"type":["string","null"],"format":"date-time"},"slaDeadline":{"type":["string","null"],"format":"date-time"},"slaStatus":{"type":["string","null"]},"ownerUserId":{"type":["string","null"]},"queueId":{"type":["string","null"]},"isPreventable":{"type":["boolean","null"]},"deniedCodes":{"type":"array","items":{"type":"string"}},"primaryCarcCode":{"type":["string","null"]},"primaryRarcCode":{"type":["string","null"]},"allCarcCodes":{"type":"array","items":{"type":"string"}},"allRarcCodes":{"type":"array","items":{"type":"string"}},"adjustmentGroupCode":{"type":["string","null"]},"denialType":{"type":["string","null"]},"autoCreatedFromEra":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"claim":{"type":["object","null"],"properties":{"id":{"type":"string"},"claimControlNumber":{"type":["string","null"]},"status":{"type":["string","null"]}},"required":["id","claimControlNumber","status"]},"patient":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]}},"required":["id","displayName"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"queue":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"payer":{"type":"object","properties":{"id":{"type":["string","null"]},"payerId":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","payerId","name"]},"counts":{"type":"object","properties":{"appeals":{"type":"integer","minimum":0},"activities":{"type":"integer","minimum":0},"files":{"type":"integer","minimum":0},"lines":{"type":"integer","minimum":0}},"required":["appeals","activities","files","lines"]}},"required":["id","organizationId","facilityId","appointmentId","claimId","patientId","payerId","category","rootCauseCode","rootCauseLabel","severity","deniedAmount","expectedAmount","paidAmount","billedAmount","status","openedAt","closedAt","appealDeadline","slaDueAt","slaDeadline","slaStatus","ownerUserId","queueId","isPreventable","deniedCodes","primaryCarcCode","primaryRarcCode","allCarcCodes","allRarcCodes","adjustmentGroupCode","denialType","autoCreatedFromEra","createdAt","updatedAt","claim","patient","facility","queue","payer","counts"]}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["denialCases","total","skip","take"]}},"required":["success","data"]},"example":{"success":true,"data":{"denialCases":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","payerId":"87726","category":"ELIGIBILITY","rootCauseCode":"example-rootcausecode","rootCauseLabel":"example-rootcauselabel","severity":"LOW","deniedAmount":"example-deniedamount","expectedAmount":"example-expectedamount","paidAmount":"example-paidamount","billedAmount":"example-billedamount","status":"NEW","openedAt":"2026-06-08T10:15:30Z","closedAt":"2026-06-08T10:15:30Z","appealDeadline":"2026-06-08T10:15:30Z","slaDueAt":"2026-06-08T10:15:30Z","slaDeadline":"2026-06-08T10:15:30Z","slaStatus":"example-slastatus","ownerUserId":"00000000-0000-4000-8000-000000000001","queueId":"00000000-0000-4000-8000-000000000001","isPreventable":true,"deniedCodes":["example-deniedcodes"],"primaryCarcCode":"example-primarycarccode","primaryRarcCode":"example-primaryrarccode","allCarcCodes":["example-allcarccodes"],"allRarcCodes":["example-allrarccodes"],"adjustmentGroupCode":"example-adjustmentgroupcode","denialType":"example-denialtype","autoCreatedFromEra":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","claim":{"id":"00000000-0000-4000-8000-000000000001","claimControlNumber":"example-claimcontrolnumber","status":"active"},"patient":{"id":"00000000-0000-4000-8000-000000000001","displayName":"Example denial_case"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example denial_case"},"queue":{"id":"00000000-0000-4000-8000-000000000001","name":"Example denial_case"},"payer":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","name":"Example denial_case"},"counts":{"appeals":1,"activities":1,"files":1,"lines":1}}],"total":1,"skip":1,"take":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/denial-management/cases/{denialCaseId}":{"get":{"operationId":"getDenialCase","summary":"Get denial case","description":"Returns one denial case when the case identifier belongs to the organization selected by the bearer API key.\n\n### When to use\nUse this after a list response, queue item, appeal draft response, reroute response, or another trusted QuickRCM workflow has supplied a denialCaseId for the same tenant.\n\n### Before calling\nAuthenticate with `denial-management:read` or `denial-management:write` and pass only a denialCaseId obtained from the same organization context.\n\n### Request guidance\nSend `denialCaseId` in the path. Do not include organization selectors, payer credentials, raw EDI, signed URLs, transcripts, or vendor payloads.\n\n### Request notes\n- `denialCaseId` is the only public selector.\n- Wrong-organization cases should be documented as not found or inaccessible.\n- No request body is declared for this endpoint.\n\n### Response semantics\nThe response is the local QuickRCM denial case record with the same public shape used by listDenialCases. It includes limited nested summaries and local workflow/deadline values, but not raw remittance content, claim payloads, full patient demographics, or appeal submission artifacts.\n\n### Response notes\n- The response contains local denial state, amounts, codes, deadlines, and relationship summaries.\n- `patient.displayName` is a convenience summary and should still be treated as PHI when linked to a denial.\n- Use mutation endpoints for status changes, remittance links, appeal draft creation, and rerouting.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization denial context unless a prior trusted response proves the case should exist. Retry transient 5xx and 429 responses with backoff; do not guess identifiers across tenants.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant resources.\n- 401 and 403 require credential, scope, or organization-context correction.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"denialCaseId","in":"path","description":"QuickRCM DenialCase identifier in the path. It must resolve inside the organization selected by the bearer API key."}],"responses":{"200":{"description":"Denial case","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"denialCase":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"facilityId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"claimId":{"type":["string","null"]},"patientId":{"type":["string","null"]},"payerId":{"type":"string"},"category":{"type":"string","enum":["ELIGIBILITY","AUTHORIZATION","CODING","MEDICAL_NECESSITY","TIMELY_FILING","COB","BENEFIT_EXHAUSTED","DUPLICATE","BUNDLING","OTHER"]},"rootCauseCode":{"type":["string","null"]},"rootCauseLabel":{"type":["string","null"]},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"deniedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"expectedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"paidAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"status":{"type":"string","enum":["NEW","IN_PROGRESS","ON_HOLD","RESUBMITTED","APPEALED","CLOSED_PAID","CLOSED_PARTIAL","CLOSED_WRITE_OFF","CLOSED_DROPPED"]},"openedAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"appealDeadline":{"type":["string","null"],"format":"date-time"},"slaDueAt":{"type":["string","null"],"format":"date-time"},"slaDeadline":{"type":["string","null"],"format":"date-time"},"slaStatus":{"type":["string","null"]},"ownerUserId":{"type":["string","null"]},"queueId":{"type":["string","null"]},"isPreventable":{"type":["boolean","null"]},"deniedCodes":{"type":"array","items":{"type":"string"}},"primaryCarcCode":{"type":["string","null"]},"primaryRarcCode":{"type":["string","null"]},"allCarcCodes":{"type":"array","items":{"type":"string"}},"allRarcCodes":{"type":"array","items":{"type":"string"}},"adjustmentGroupCode":{"type":["string","null"]},"denialType":{"type":["string","null"]},"autoCreatedFromEra":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"claim":{"type":["object","null"],"properties":{"id":{"type":"string"},"claimControlNumber":{"type":["string","null"]},"status":{"type":["string","null"]}},"required":["id","claimControlNumber","status"]},"patient":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]}},"required":["id","displayName"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"queue":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"payer":{"type":"object","properties":{"id":{"type":["string","null"]},"payerId":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","payerId","name"]},"counts":{"type":"object","properties":{"appeals":{"type":"integer","minimum":0},"activities":{"type":"integer","minimum":0},"files":{"type":"integer","minimum":0},"lines":{"type":"integer","minimum":0}},"required":["appeals","activities","files","lines"]}},"required":["id","organizationId","facilityId","appointmentId","claimId","patientId","payerId","category","rootCauseCode","rootCauseLabel","severity","deniedAmount","expectedAmount","paidAmount","billedAmount","status","openedAt","closedAt","appealDeadline","slaDueAt","slaDeadline","slaStatus","ownerUserId","queueId","isPreventable","deniedCodes","primaryCarcCode","primaryRarcCode","allCarcCodes","allRarcCodes","adjustmentGroupCode","denialType","autoCreatedFromEra","createdAt","updatedAt","claim","patient","facility","queue","payer","counts"]}},"required":["denialCase"]}},"required":["success","data"]},"example":{"success":true,"data":{"denialCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","payerId":"87726","category":"ELIGIBILITY","rootCauseCode":"example-rootcausecode","rootCauseLabel":"example-rootcauselabel","severity":"LOW","deniedAmount":"example-deniedamount","expectedAmount":"example-expectedamount","paidAmount":"example-paidamount","billedAmount":"example-billedamount","status":"NEW","openedAt":"2026-06-08T10:15:30Z","closedAt":"2026-06-08T10:15:30Z","appealDeadline":"2026-06-08T10:15:30Z","slaDueAt":"2026-06-08T10:15:30Z","slaDeadline":"2026-06-08T10:15:30Z","slaStatus":"example-slastatus","ownerUserId":"00000000-0000-4000-8000-000000000001","queueId":"00000000-0000-4000-8000-000000000001","isPreventable":true,"deniedCodes":["example-deniedcodes"],"primaryCarcCode":"example-primarycarccode","primaryRarcCode":"example-primaryrarccode","allCarcCodes":["example-allcarccodes"],"allRarcCodes":["example-allrarccodes"],"adjustmentGroupCode":"example-adjustmentgroupcode","denialType":"example-denialtype","autoCreatedFromEra":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","claim":{"id":"00000000-0000-4000-8000-000000000001","claimControlNumber":"example-claimcontrolnumber","status":"active"},"patient":{"id":"00000000-0000-4000-8000-000000000001","displayName":"Example denial_case"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example denial_case"},"queue":{"id":"00000000-0000-4000-8000-000000000001","name":"Example denial_case"},"payer":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","name":"Example denial_case"},"counts":{"appeals":1,"activities":1,"files":1,"lines":1}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial case not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/denial-management/cases/{denialCaseId}/status":{"put":{"operationId":"updateDenialCaseStatus","summary":"Update denial case status","description":"Updates the local status of one organization-owned denial case after validating the requested transition and writes a DenialActivity audit record.\n\n### When to use\nUse this when staff or automation moves a denial case through local workflow states, such as starting work, marking it appealed, or closing it with a paid, partial, write-off, or dropped outcome.\n\n### Before calling\nAuthenticate with `denial-management:write`. Read the current denial case first, choose a status that is valid for the current state machine transition, and prepare only a concise sanitized note if one is needed.\n\n### Request guidance\n`status` is required. `note` is optional and capped at 2000 characters. Although the OpenAPI enum lists all public DenialStatus values, the handler also runs the denial state machine and can reject enum-valid statuses that are not valid from the case's current status.\n\n### Request notes\n- Use `status`, not `targetStatus`, in the body.\n- Do not include PHI-heavy narratives, raw payer payloads, EDI, credentials, or transcripts in `note`.\n- State-machine validation means terminal statuses and legacy status mappings can reject otherwise schema-valid requests.\n\n### Response semantics\nA 200 response returns the updated local denial case projection and `meta.organizationId`. The endpoint does not submit an appeal, contact a payer, post a payment, or change claim adjudication.\n\n### Response notes\n- `meta.organizationId` echoes the API key organization.\n- The returned denial case is a local projection after applying the status value.\n- A status update is local workflow evidence, not payer acceptance or payment.\n\n### Errors and retries\nTreat invalid transitions as non-retryable until you re-read the case state. Treat 404 as missing or wrong-tenant case context. If a request times out, re-read the case before retrying so you do not add duplicate activity notes.\n\n### Error notes\n- 400 can mean schema validation failed or the requested transition is invalid for the current status.\n- 404 can mean the case is unavailable to the authenticated organization.\n- Retry only after refreshing current case status when concurrency is possible.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"denialCaseId","in":"path","description":"QuickRCM DenialCase identifier in the path. It must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["NEW","IN_PROGRESS","ON_HOLD","RESUBMITTED","APPEALED","CLOSED_PAID","CLOSED_PARTIAL","CLOSED_WRITE_OFF","CLOSED_DROPPED"],"description":"Required target local denial case status. The schema enum is not a promise that the transition is valid from every current status."},"note":{"type":"string","maxLength":2000,"description":"Optional sanitized internal activity note, capped at 2000 characters."}},"required":["status"]},"example":{"status":"NEW","note":"Example denial_case_statu note"}}},"description":"`status` is required. `note` is optional and capped at 2000 characters. Although the OpenAPI enum lists all public DenialStatus values, the handler also runs the denial state machine and can reject enum-valid statuses that are not valid from the case's current status."},"responses":{"200":{"description":"Updated denial case","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"denialCase":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"facilityId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"claimId":{"type":["string","null"]},"patientId":{"type":["string","null"]},"payerId":{"type":"string"},"category":{"type":"string","enum":["ELIGIBILITY","AUTHORIZATION","CODING","MEDICAL_NECESSITY","TIMELY_FILING","COB","BENEFIT_EXHAUSTED","DUPLICATE","BUNDLING","OTHER"]},"rootCauseCode":{"type":["string","null"]},"rootCauseLabel":{"type":["string","null"]},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"deniedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"expectedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"paidAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"status":{"type":"string","enum":["NEW","IN_PROGRESS","ON_HOLD","RESUBMITTED","APPEALED","CLOSED_PAID","CLOSED_PARTIAL","CLOSED_WRITE_OFF","CLOSED_DROPPED"]},"openedAt":{"type":"string","format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"appealDeadline":{"type":["string","null"],"format":"date-time"},"slaDueAt":{"type":["string","null"],"format":"date-time"},"slaDeadline":{"type":["string","null"],"format":"date-time"},"slaStatus":{"type":["string","null"]},"ownerUserId":{"type":["string","null"]},"queueId":{"type":["string","null"]},"isPreventable":{"type":["boolean","null"]},"deniedCodes":{"type":"array","items":{"type":"string"}},"primaryCarcCode":{"type":["string","null"]},"primaryRarcCode":{"type":["string","null"]},"allCarcCodes":{"type":"array","items":{"type":"string"}},"allRarcCodes":{"type":"array","items":{"type":"string"}},"adjustmentGroupCode":{"type":["string","null"]},"denialType":{"type":["string","null"]},"autoCreatedFromEra":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"claim":{"type":["object","null"],"properties":{"id":{"type":"string"},"claimControlNumber":{"type":["string","null"]},"status":{"type":["string","null"]}},"required":["id","claimControlNumber","status"]},"patient":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]}},"required":["id","displayName"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"queue":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"payer":{"type":"object","properties":{"id":{"type":["string","null"]},"payerId":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","payerId","name"]},"counts":{"type":"object","properties":{"appeals":{"type":"integer","minimum":0},"activities":{"type":"integer","minimum":0},"files":{"type":"integer","minimum":0},"lines":{"type":"integer","minimum":0}},"required":["appeals","activities","files","lines"]}},"required":["id","organizationId","facilityId","appointmentId","claimId","patientId","payerId","category","rootCauseCode","rootCauseLabel","severity","deniedAmount","expectedAmount","paidAmount","billedAmount","status","openedAt","closedAt","appealDeadline","slaDueAt","slaDeadline","slaStatus","ownerUserId","queueId","isPreventable","deniedCodes","primaryCarcCode","primaryRarcCode","allCarcCodes","allRarcCodes","adjustmentGroupCode","denialType","autoCreatedFromEra","createdAt","updatedAt","claim","patient","facility","queue","payer","counts"]}},"required":["denialCase"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"denialCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","payerId":"87726","category":"ELIGIBILITY","rootCauseCode":"example-rootcausecode","rootCauseLabel":"example-rootcauselabel","severity":"LOW","deniedAmount":"example-deniedamount","expectedAmount":"example-expectedamount","paidAmount":"example-paidamount","billedAmount":"example-billedamount","status":"NEW","openedAt":"2026-06-08T10:15:30Z","closedAt":"2026-06-08T10:15:30Z","appealDeadline":"2026-06-08T10:15:30Z","slaDueAt":"2026-06-08T10:15:30Z","slaDeadline":"2026-06-08T10:15:30Z","slaStatus":"example-slastatus","ownerUserId":"00000000-0000-4000-8000-000000000001","queueId":"00000000-0000-4000-8000-000000000001","isPreventable":true,"deniedCodes":["example-deniedcodes"],"primaryCarcCode":"example-primarycarccode","primaryRarcCode":"example-primaryrarccode","allCarcCodes":["example-allcarccodes"],"allRarcCodes":["example-allrarccodes"],"adjustmentGroupCode":"example-adjustmentgroupcode","denialType":"example-denialtype","autoCreatedFromEra":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","claim":{"id":"00000000-0000-4000-8000-000000000001","claimControlNumber":"example-claimcontrolnumber","status":"active"},"patient":{"id":"00000000-0000-4000-8000-000000000001","displayName":"Example denial_case_statu"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example denial_case_statu"},"queue":{"id":"00000000-0000-4000-8000-000000000001","name":"Example denial_case_statu"},"payer":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","name":"Example denial_case_statu"},"counts":{"appeals":1,"activities":1,"files":1,"lines":1}}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial case not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/denial-management/cases/{denialCaseId}/remittances/{remittanceId}":{"post":{"operationId":"linkRemittanceToDenial","summary":"Link remittance to denial case","description":"Associates an organization-owned remittance record with an organization-owned denial case by storing the remittance identifier on the case.\n\n### When to use\nUse this when a local remittance has already been ingested or identified and needs to be connected to a denial case for reconciliation, audit, or follow-up context.\n\n### Before calling\nAuthenticate with `denial-management:write`. Resolve both `denialCaseId` and `remittanceId` from trusted QuickRCM responses in the same organization.\n\n### Request guidance\nPass both identifiers in the path. The request body is empty in the public schema. Do not send raw 835/ERA content, payer payloads, EDI files, payment details, or tenant selectors.\n\n### Request notes\n- `denialCaseId` and `remittanceId` must both resolve inside the API key organization.\n- The endpoint declares no request-body fields.\n- Keep remittance payloads in ingestion/storage workflows, not this link request.\n\n### Response semantics\nA 200 response returns the linked denialCaseId, remittanceId, and `meta.organizationId`. It confirms only a local association; it does not parse a remittance, post payments, update adjudication, or create a denial case.\n\n### Response notes\n- The response returns identifiers only.\n- The operation is a local DenialCase update, not ERA parsing or payment posting.\n- Use getDenialCase afterward if the caller needs to confirm current case state.\n\n### Errors and retries\nA 404 can mean either the denial case or remittance was not found in the authenticated organization. After a timeout, re-read the denial case before retrying because the association may already have been written.\n\n### Error notes\n- 404 may refer to either identifier being missing or outside the organization.\n- 401 and 403 require credential or scope correction.\n- Retry transient failures only after checking current link state.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"denialCaseId","in":"path","description":"QuickRCM DenialCase identifier in the path."},{"schema":{"type":"string","minLength":1},"required":true,"name":"remittanceId","in":"path","description":"QuickRCM Remittance identifier in the path. It must belong to the same authenticated organization as the denial case."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"Pass both identifiers in the path. The request body is empty in the public schema. Do not send raw 835/ERA content, payer payloads, EDI files, payment details, or tenant selectors."},"responses":{"200":{"description":"Remittance link created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"denialCaseId":{"type":"string"},"remittanceId":{"type":"string"}},"required":["denialCaseId","remittanceId"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"denialCaseId":"00000000-0000-4000-8000-000000000001","remittanceId":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial case or remittance not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/denial-management/cases/{denialCaseId}/appeals":{"post":{"operationId":"createDenialAppeal","summary":"Create denial appeal draft","description":"Creates a local draft appeal for an organization-owned denial case, or returns the existing draft appeal for that case.\n\n### When to use\nUse this when a denial case is ready for appeal preparation and the integration needs a QuickRCM draft appeal record before staff review, document gathering, letter editing, or downstream appeal submission handled elsewhere.\n\n### Before calling\nAuthenticate with `denial-management:write`. Confirm the denial case belongs to the tenant and decide whether optional `letterHtml` should seed or update the draft appeal content.\n\n### Request guidance\n`letterHtml` is optional and capped at 100000 characters. If a draft appeal already exists, the current handler returns 200 with `idempotencyStatus: existing`; when `letterHtml` is supplied and the delegate supports `updateMany`, it updates the existing draft letter HTML before returning the existing draft summary.\n\n### Request notes\n- Use `denialCaseId` from a trusted Denial Management response.\n- Keep `letterHtml` sanitized; do not include real PHI in examples, credentials, raw EDI, or raw payer portal content.\n- This endpoint does not expose appeal level selection in the public request body.\n\n### Response semantics\nA 201 response means a local DRAFT appeal was created with level `LEVEL_1_RECONSIDERATION`; a 200 response means an existing DRAFT appeal was returned. Neither response submits an appeal, sends attachments, contacts a payer, or guarantees recovery.\n\n### Response notes\n- `idempotencyStatus` is `created` for new drafts and `existing` when a draft already exists.\n- Returned appeal fields are limited to id, organizationId, denialCaseId, claimId, level, and status.\n- External appeal submission is outside this endpoint.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant denial case context. After a timeout, call the endpoint or read local appeal state before creating other appeal records; the handler is draft-aware but does not expose a request idempotency key.\n\n### Error notes\n- 400 can indicate invalid body shape or overlong letterHtml.\n- 404 means the denial case was not found for the authenticated organization.\n- Retry cautiously after checking for an existing draft.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"denialCaseId","in":"path","description":"QuickRCM DenialCase identifier used to create or find a local draft appeal."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"letterHtml":{"type":"string","maxLength":100000,"description":"Optional HTML content to store on the local draft appeal. Keep examples synthetic and do not include credentials or raw payer payloads."}}},"example":{"letterHtml":"example-letterhtml"}}},"description":"`letterHtml` is optional and capped at 100000 characters. If a draft appeal already exists, the current handler returns 200 with `idempotencyStatus: existing`; when `letterHtml` is supplied and the delegate supports `updateMany`, it updates the existing draft letter HTML before returning the existing draft summary."},"responses":{"200":{"description":"Existing draft appeal returned","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string"},"status":{"type":"string"}},"required":["id","organizationId","denialCaseId","claimId","level","status"]},"idempotencyStatus":{"type":"string","enum":["created","existing"]}},"required":["appeal","idempotencyStatus"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"example-level","status":"active"},"idempotencyStatus":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"201":{"description":"Draft appeal created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"denialCaseId":{"type":"string"},"claimId":{"type":["string","null"]},"level":{"type":"string"},"status":{"type":"string"}},"required":["id","organizationId","denialCaseId","claimId","level","status"]},"idempotencyStatus":{"type":"string","enum":["created","existing"]}},"required":["appeal","idempotencyStatus"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","denialCaseId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","level":"example-level","status":"active"},"idempotencyStatus":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial case not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/denial-management/queue-rules":{"get":{"operationId":"listDenialQueueRules","summary":"List denial queue configuration","description":"Returns Denial Management queues and queue routing rules configured for the organization selected by the bearer API key.\n\n### When to use\nUse this endpoint to populate routing configuration pages, validate rule setup before creating or updating rules, or find queue identifiers before rerouting a denial case.\n\n### Before calling\nAuthenticate with `denial-management:read` or `denial-management:write`. No query parameters are declared, so callers should cache or refresh the full organization-local queue configuration as appropriate.\n\n### Request guidance\nDo not send pagination, search, or organization selectors; the public contract declares no request fields for this endpoint.\n\n### Request notes\n- No query parameters are declared in the OpenAPI contract.\n- Use returned `queues[].id` values for createDenialQueueRule action targets and rerouteDenialCase requests.\n- Rules are ordered by priority in the current handler.\n\n### Response semantics\nThe response contains local queue definitions and queue routing rules. Queues include capacity, default SLA, default assignment, member role/user arrays, and default flags. Rules include priority, active state, conditions, and actions. The endpoint does not evaluate rules or move denial cases.\n\n### Response notes\n- `data.queues` and `data.rules` are local configuration state.\n- `conditions` and `actions` are structured JSON values and should be interpreted using the documented rule fields.\n- Listing configuration does not process existing cases.\n\n### Errors and retries\nTreat 401 and 403 as credential or scope issues. Retry transient 5xx and 429 responses with backoff. Do not retry malformed requests with invented query parameters.\n\n### Error notes\n- 403 means Denial Management access is missing.\n- 500 can indicate server-side entity wiring or data access failure.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Denial queue configuration","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"currentCount":{"type":"integer","minimum":0},"maxCapacity":{"type":["integer","null"]},"defaultSlaHours":{"type":["integer","null"]},"defaultAssignmentMethod":{"type":["string","null"]},"memberRoles":{"type":"array","items":{"type":"string"}},"memberUserIds":{"type":"array","items":{"type":"string"}},"isDefault":{"type":"boolean"}},"required":["id","organizationId","name","description","currentCount","maxCapacity","defaultSlaHours","defaultAssignmentMethod","memberRoles","memberUserIds","isDefault"]}},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"queueId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"priority":{"type":"integer"},"isActive":{"type":"boolean"},"conditions":{},"actions":{}},"required":["id","organizationId","queueId","name","description","priority","isActive"]}}},"required":["queues","rules"]}},"required":["success","data"]},"example":{"success":true,"data":{"queues":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example denial_queue_rule","description":"Example denial_queue_rule note","currentCount":1,"maxCapacity":1,"defaultSlaHours":1,"defaultAssignmentMethod":"example-defaultassignmentmethod","memberRoles":["example-memberroles"],"memberUserIds":["example-memberuserids"],"isDefault":true}],"rules":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","queueId":"00000000-0000-4000-8000-000000000001","name":"Example denial_queue_rule","description":"Example denial_queue_rule note","priority":1,"isActive":true,"conditions":"example-conditions","actions":"example-actions"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createDenialQueueRule","summary":"Create denial queue rule","description":"Creates a local Denial Management routing rule after validating that the target queue and any action references belong to the authenticated organization.\n\n### When to use\nUse this when configuring how future or manually evaluated denial cases should be routed by category, severity, payer, code, dollar range, age, facility, deadline, or other documented rule conditions.\n\n### Before calling\nAuthenticate with `denial-management:write`. Retrieve queue identifiers with listDenialQueueRules, and confirm any `assignToUserId` or `notifyUserIds` are active organization members.\n\n### Request guidance\n`queueId` and `name` are required. Top-level `priority` is an integer sort order from 0 through 10000 and defaults to 100. `isActive` defaults to true, `conditions` defaults to an empty object, and `actions` defaults to `{ \"queueId\": body.queueId }` when omitted. If `actions` is provided, its `queueId` is required by the create schema. The schema allows pass-through keys, but public docs should emphasize documented fields and avoid relying on extra keys.\n\n### Request notes\n- `name` is capped at 255 characters and `description` at 2000 characters.\n- Top-level `priority` is numeric rule ordering. Nested `actions.priority` is a string action label capped at 64 characters.\n- Keep rule names, descriptions, tags, and pattern values free of PHI, credentials, and raw payer payloads.\n\n### Response semantics\nA 201 response returns the created local routing rule and `meta.organizationId`. This creates configuration only; it does not automatically reroute existing denial cases or contact external systems.\n\n### Response notes\n- The returned rule stores local conditions and actions JSON.\n- Rule creation does not run the routing engine against existing cases.\n- `meta.organizationId` is derived from the API key.\n\n### Errors and retries\nA 404 can mean the main queueId, actions.queueId, assignToUserId, or notifyUserIds cannot be resolved in the authenticated organization. After a timeout, list queue rules before retrying to avoid duplicate rule names or priorities.\n\n### Error notes\n- 400 can indicate missing required fields, invalid enum values, or out-of-range numeric fields.\n- 404 can indicate referenced queues or users are unavailable to the tenant.\n- Retry only after checking whether the rule was already created.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueId":{"type":"string","minLength":1,"description":"Required Denial Management queue identifier. The queue must belong to the authenticated organization."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Required routing rule name, capped at 255 characters. Keep it operational and PHI-minimal."},"description":{"type":["string","null"],"maxLength":2000,"description":"Optional routing rule description, nullable and capped at 2000 characters."},"priority":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"Optional top-level rule ordering integer from 0 through 10000. Lower values sort earlier in the current list handler."},"isActive":{"type":"boolean","description":"Optional flag indicating whether the rule is active. Defaults to true on create."},"conditions":{"type":"object","properties":{"denialCategories":{"type":"array","items":{"type":"string","enum":["ELIGIBILITY","AUTHORIZATION","CODING","MEDICAL_NECESSITY","TIMELY_FILING","COB","BENEFIT_EXHAUSTED","DUPLICATE","BUNDLING","OTHER"]},"description":"Optional array of denial category enum values to match."},"severities":{"type":"array","items":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"description":"Optional array of denial severity enum values to match."},"denialTypes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional array of denial type labels to match. Each string is capped at 128 characters."},"preventabilityClasses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional array of preventability classification labels to match. Each string is capped at 128 characters."},"rootCauseDepartments":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional array of root-cause department labels to match. Each string is capped at 128 characters."},"payerIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional array of payer identifiers to match. Each string is capped at 128 characters."},"payerNamePatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Optional payer-name pattern strings, each capped at 255 characters. Avoid storing unnecessary PHI or secrets."},"cptCodePatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"description":"Optional CPT-code pattern strings, each capped at 64 characters."},"carcCodes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":16},"description":"Optional Claim Adjustment Reason Code strings, each capped at 16 characters."},"dollarRange":{"type":"object","properties":{"min":{"type":["number","null"],"minimum":0,"description":"Optional minimum denied-dollar threshold for the rule condition. Values are numbers and must be at least 0."},"max":{"type":["number","null"],"minimum":0,"description":"Optional maximum denied-dollar threshold for the rule condition. Values are numbers and must be at least 0."}},"description":"Optional minimum/maximum denied-dollar range used in a routing condition."},"ageDaysRange":{"type":"object","properties":{"min":{"type":["integer","null"],"minimum":0,"description":"Optional minimum denial age in days. Values are integers and must be at least 0."},"max":{"type":["integer","null"],"minimum":0,"description":"Optional maximum denial age in days. Values are integers and must be at least 0."}},"description":"Optional minimum/maximum denial-age range in days used in a routing condition."},"facilityIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional array of organization-scoped facility identifiers. Each string is capped at 128 characters."},"hasAppealDeadline":{"type":"boolean","description":"Optional boolean condition indicating whether a case has an appeal deadline."},"daysUntilAppealDeadline":{"type":"object","properties":{"min":{"type":["integer","null"],"minimum":0,"description":"Optional lower bound for days until appeal deadline. Values are integers and must be at least 0."},"max":{"type":["integer","null"],"minimum":0,"description":"Optional upper bound for days until appeal deadline. Values are integers and must be at least 0."}},"description":"Optional minimum/maximum range for days remaining until appeal deadline."}},"default":{},"description":"Optional structured matching criteria for denial routing. Defaults to an empty object."},"actions":{"type":"object","properties":{"queueId":{"type":"string","minLength":1,"description":"Required action queue identifier when actions is provided on create. It must belong to the authenticated organization."},"priority":{"type":"string","minLength":1,"maxLength":64,"description":"Optional string action priority or label capped at 64 characters. This is not the same field as the top-level numeric rule priority."},"assignToUserId":{"type":"string","minLength":1,"maxLength":128,"description":"Optional QuickRCM user identifier capped at 128 characters. The user must be an active member of the authenticated organization."},"assignToRole":{"type":"string","minLength":1,"maxLength":128,"description":"Optional role label capped at 128 characters for local assignment logic."},"assignmentMethod":{"type":"string","minLength":1,"maxLength":128,"description":"Optional local assignment method label capped at 128 characters."},"slaHours":{"type":"integer","exclusiveMinimum":0,"description":"Optional positive integer SLA override in hours."},"autoEscalateAfterHours":{"type":"integer","exclusiveMinimum":0,"description":"Optional positive integer auto-escalation threshold in hours."},"notifyUserIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional array of QuickRCM user identifiers. Each user must be an active member of the authenticated organization."},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional array of local routing tags, each capped at 128 characters."}},"required":["queueId"],"description":"Optional structured routing actions. When omitted, the handler stores an action that routes to the request queueId."}},"required":["queueId","name"]},"example":{"queueId":"00000000-0000-4000-8000-000000000001","name":"Example denial_queue_rule","description":"Example denial_queue_rule note","priority":1,"isActive":true,"conditions":{},"actions":{"queueId":"00000000-0000-4000-8000-000000000001","priority":"example-priority","assignToUserId":"00000000-0000-4000-8000-000000000001","assignToRole":"example-assigntorole","assignmentMethod":"example-assignmentmethod","slaHours":1,"autoEscalateAfterHours":1,"notifyUserIds":["example-notifyuserids"],"tags":["example-tags"]}}}},"description":"`queueId` and `name` are required. Top-level `priority` is an integer sort order from 0 through 10000 and defaults to 100. `isActive` defaults to true, `conditions` defaults to an empty object, and `actions` defaults to `{ \"queueId\": body.queueId }` when omitted. If `actions` is provided, its `queueId` is required by the create schema. The schema allows pass-through keys, but public docs should emphasize documented fields and avoid relying on extra keys."},"responses":{"201":{"description":"Denial queue rule created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"rule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"queueId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"priority":{"type":"integer"},"isActive":{"type":"boolean"},"conditions":{},"actions":{}},"required":["id","organizationId","queueId","name","description","priority","isActive"]}},"required":["rule"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"rule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","queueId":"00000000-0000-4000-8000-000000000001","name":"Example denial_queue_rule","description":"Example denial_queue_rule note","priority":1,"isActive":true,"conditions":"example-conditions","actions":"example-actions"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial queue not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/denial-management/queue-rules/{ruleId}":{"put":{"operationId":"updateDenialQueueRule","summary":"Update denial queue rule","description":"Updates one organization-owned Denial Management routing rule after validating the rule exists and any merged action references remain organization-scoped.\n\n### When to use\nUse this when changing a rule name, description, priority, active flag, matching conditions, or routing/assignment actions.\n\n### Before calling\nAuthenticate with `denial-management:write`. Load the existing rule first so the caller understands current conditions and actions, especially because action updates are merged with existing actions.\n\n### Request guidance\nAt least one editable field is required. `conditions` accepts the same shape as createDenialQueueRule and replaces the stored conditions object when supplied. `actions` accepts the same documented action fields as createDenialQueueRule, is partial on update, and is merged with the existing actions object before queue and user references are validated.\n\n### Request notes\n- `ruleId` selects the route rule in the path.\n- Send only intended fields; `conditions` is not merged.\n- Top-level `priority` is numeric rule ordering. Nested `actions.priority` is a string action label capped at 64 characters.\n\n### Response semantics\nA 200 response returns the local rule projection after applying the update and `meta.organizationId`. Existing denial cases are not automatically rerouted by this endpoint.\n\n### Response notes\n- The response is local routing configuration.\n- Updated actions may include existing action fields plus the supplied patch.\n- No denial case status, owner, or queue is changed by this endpoint alone.\n\n### Errors and retries\nTreat 400 as an empty or invalid update body. Treat 404 as missing or wrong-tenant rule, action queue, or action user context. After a timeout, re-read the rule before retrying to avoid overwriting concurrent admin edits.\n\n### Error notes\n- 400 can mean the body contains no editable fields.\n- 404 can mean the rule or referenced action target is outside the authenticated organization.\n- Retry after refreshing current rule state.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ruleId","in":"path","description":"QuickRCM DenialQueueRule identifier in the path. It must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional replacement routing rule name, capped at 255 characters."},"description":{"type":["string","null"],"maxLength":2000,"description":"Optional replacement routing rule description, nullable and capped at 2000 characters."},"priority":{"type":["integer","null"],"minimum":0,"maximum":10000,"description":"Optional replacement top-level rule ordering integer from 0 through 10000."},"isActive":{"type":"boolean","description":"Optional replacement active flag."},"conditions":{"type":"object","properties":{"denialCategories":{"type":"array","items":{"type":"string","enum":["ELIGIBILITY","AUTHORIZATION","CODING","MEDICAL_NECESSITY","TIMELY_FILING","COB","BENEFIT_EXHAUSTED","DUPLICATE","BUNDLING","OTHER"]},"description":"Optional replacement array of denial category enum values to match."},"severities":{"type":"array","items":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"description":"Optional replacement array of denial severity enum values to match."},"denialTypes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional replacement array of denial type labels, each capped at 128 characters."},"preventabilityClasses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional replacement array of preventability classification labels, each capped at 128 characters."},"rootCauseDepartments":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional replacement array of root-cause department labels, each capped at 128 characters."},"payerIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional replacement array of payer identifiers, each capped at 128 characters."},"payerNamePatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Optional replacement payer-name pattern strings, each capped at 255 characters."},"cptCodePatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"description":"Optional replacement CPT-code pattern strings, each capped at 64 characters."},"carcCodes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":16},"description":"Optional replacement Claim Adjustment Reason Code strings, each capped at 16 characters."},"dollarRange":{"type":"object","properties":{"min":{"type":["number","null"],"minimum":0,"description":"Optional replacement minimum denied-dollar threshold. Values are numbers and must be at least 0."},"max":{"type":["number","null"],"minimum":0,"description":"Optional replacement maximum denied-dollar threshold. Values are numbers and must be at least 0."}},"description":"Optional minimum/maximum denied-dollar range used in a routing condition."},"ageDaysRange":{"type":"object","properties":{"min":{"type":["integer","null"],"minimum":0,"description":"Optional replacement minimum denial age in days. Values are integers and must be at least 0."},"max":{"type":["integer","null"],"minimum":0,"description":"Optional replacement maximum denial age in days. Values are integers and must be at least 0."}},"description":"Optional minimum/maximum denial-age range in days used in a routing condition."},"facilityIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional replacement array of organization-scoped facility identifiers, each capped at 128 characters."},"hasAppealDeadline":{"type":"boolean","description":"Optional replacement boolean condition indicating whether a case has an appeal deadline."},"daysUntilAppealDeadline":{"type":"object","properties":{"min":{"type":["integer","null"],"minimum":0,"description":"Optional replacement lower bound for days until appeal deadline. Values are integers and must be at least 0."},"max":{"type":["integer","null"],"minimum":0,"description":"Optional replacement upper bound for days until appeal deadline. Values are integers and must be at least 0."}},"description":"Optional minimum/maximum range for days remaining until appeal deadline."}},"description":"Optional replacement conditions object for the rule. It accepts the same fields as createDenialQueueRule conditions."},"actions":{"type":"object","properties":{"queueId":{"type":"string","minLength":1,"description":"Optional action queue identifier on update, but if supplied it must belong to the authenticated organization."},"priority":{"type":"string","minLength":1,"maxLength":64,"description":"Optional string action priority or label capped at 64 characters. Do not confuse it with top-level numeric rule priority."},"assignToUserId":{"type":"string","minLength":1,"maxLength":128,"description":"Optional action assignee user identifier capped at 128 characters. It must be an active member of the organization."},"assignToRole":{"type":"string","minLength":1,"maxLength":128,"description":"Optional role label capped at 128 characters for local assignment logic."},"assignmentMethod":{"type":"string","minLength":1,"maxLength":128,"description":"Optional local assignment method label capped at 128 characters."},"slaHours":{"type":"integer","exclusiveMinimum":0,"description":"Optional positive integer SLA override in hours."},"autoEscalateAfterHours":{"type":"integer","exclusiveMinimum":0,"description":"Optional positive integer auto-escalation threshold in hours."},"notifyUserIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional notification user identifiers. Every user must be an active organization member."},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"description":"Optional array of local routing tags, each capped at 128 characters."}},"description":"Optional partial action update. The handler merges it with existing actions before validation."}}},"example":{"name":"Example denial_queue_rule","description":"Example denial_queue_rule note","priority":1,"isActive":true,"conditions":{"denialCategories":["ELIGIBILITY"],"severities":["LOW"],"denialTypes":["example-denialtypes"],"preventabilityClasses":["example-preventabilityclasses"],"rootCauseDepartments":["example-rootcausedepartments"],"payerIds":["example-payerids"],"payerNamePatterns":["Example denial_queue_rule"],"cptCodePatterns":["example-cptcodepatterns"]},"actions":{"queueId":"00000000-0000-4000-8000-000000000001","priority":"example-priority","assignToUserId":"00000000-0000-4000-8000-000000000001","assignToRole":"example-assigntorole","assignmentMethod":"example-assignmentmethod","slaHours":1,"autoEscalateAfterHours":1,"notifyUserIds":["example-notifyuserids"]}}}},"description":"At least one editable field is required. `conditions` accepts the same shape as createDenialQueueRule and replaces the stored conditions object when supplied. `actions` accepts the same documented action fields as createDenialQueueRule, is partial on update, and is merged with the existing actions object before queue and user references are validated."},"responses":{"200":{"description":"Denial queue rule updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"rule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"queueId":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"priority":{"type":"integer"},"isActive":{"type":"boolean"},"conditions":{},"actions":{}},"required":["id","organizationId","queueId","name","description","priority","isActive"]}},"required":["rule"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"rule":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","queueId":"00000000-0000-4000-8000-000000000001","name":"Example denial_queue_rule","description":"Example denial_queue_rule note","priority":1,"isActive":true,"conditions":"example-conditions","actions":"example-actions"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial queue rule not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/denial-management/cases/{denialCaseId}/route":{"put":{"operationId":"rerouteDenialCase","summary":"Reroute denial case","description":"Moves one organization-owned denial case to another organization-owned Denial Management queue, updates queue counters when the queue changes, and records a local reroute activity.\n\n### When to use\nUse this for manual reassignment, supervisor triage, escalation to a specialized queue, or an integration-driven queue move after a routing decision has already been made.\n\n### Before calling\nAuthenticate with `denial-management:write`. Resolve the denial case and destination queue from the same organization, and prepare an optional sanitized reason.\n\n### Request guidance\n`queueId` is required and must reference a Denial Management queue in the authenticated organization. `reason` is optional and capped at 2000 characters. This endpoint does not evaluate routing rules; the caller supplies the destination queue.\n\n### Request notes\n- Use queue IDs from listDenialQueueRules.\n- Keep `reason` concise and do not include raw payer payloads, credentials, or unnecessary PHI.\n- No owner assignment or status transition is declared in this endpoint.\n\n### Response semantics\nA 200 response returns the denialCaseId, oldQueueId, newQueueId, and `meta.organizationId`. It confirms a local queue assignment change and activity record, not a payer workflow action.\n\n### Response notes\n- `oldQueueId` may be null when the case did not have a queue.\n- Queue counters are adjusted only when the destination differs from the current queue.\n- The returned identifiers are local workflow state.\n\n### Errors and retries\nA 404 can mean either the denial case or queue cannot be resolved inside the authenticated organization. After a timeout, re-read the case and queue counts before retrying to avoid confusing duplicate activity records.\n\n### Error notes\n- 404 can refer to either the case or destination queue.\n- 400 can indicate missing queueId or an overlong reason.\n- Retry only after checking current case queue state.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"denialCaseId","in":"path","description":"QuickRCM DenialCase identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueId":{"type":"string","minLength":1,"description":"Required destination Denial Management queue identifier. It must belong to the authenticated organization."},"reason":{"type":"string","maxLength":2000,"description":"Optional sanitized local reroute note, capped at 2000 characters."}},"required":["queueId"]},"example":{"queueId":"00000000-0000-4000-8000-000000000001","reason":"example-reason"}}},"description":"`queueId` is required and must reference a Denial Management queue in the authenticated organization. `reason` is optional and capped at 2000 characters. This endpoint does not evaluate routing rules; the caller supplies the destination queue."},"responses":{"200":{"description":"Denial case rerouted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"denialCaseId":{"type":"string"},"oldQueueId":{"type":["string","null"]},"newQueueId":{"type":"string"}},"required":["denialCaseId","oldQueueId","newQueueId"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"denialCaseId":"00000000-0000-4000-8000-000000000001","oldQueueId":"00000000-0000-4000-8000-000000000001","newQueueId":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial case or queue not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/denial-management/documents/extract":{"post":{"operationId":"extractDenialDocument","summary":"Validate denial document extraction","description":"Validates or dry-runs a denial document extraction request using metadata only; public API callers cannot trigger OCR, LLM extraction, storage writes, queueing, or payer calls through this endpoint.\n\n### When to use\nUse this endpoint to confirm that a planned denial-document extraction request is well formed and optionally tied to an organization-owned denial case before using a separate internal or future ingestion workflow.\n\n### Before calling\nAuthenticate with `denial-management:write`. Provide `fileName`, `fileSizeBytes`, and either `validateOnly` or `dryRun`. If supplying `denialCaseId`, resolve it from the same organization first.\n\n### Request guidance\n`fileName` is required and capped at 255 characters. `fileSizeBytes` is required, must be at least 1 byte, and is capped at 10 MiB. At least one of `validateOnly` or `dryRun` must be true. Do not send file bytes, signed URLs, S3 keys, OCR text, transcripts, raw payer documents, or extracted vendor payloads.\n\n### Request notes\n- `validateOnly` or `dryRun` is required for API-key callers.\n- This endpoint accepts metadata only, not multipart upload or binary content.\n- If both `dryRun` and `validateOnly` are true, the current handler reports `mode: dryRun`.\n\n### Response semantics\nA 200 response returns `mode`, `extractionPerformed: false`, `queued: false`, the optional denialCaseId, fileName, fileSizeBytes, and `meta.organizationId`. The response is validation evidence only.\n\n### Response notes\n- `extractionPerformed` is always false in the public response schema.\n- `queued` is always false in the public response schema.\n- `mode` is `dryRun` when dryRun is true; otherwise it is `validateOnly`.\n\n### Errors and retries\nA 400 is expected when neither validateOnly nor dryRun is true, when file metadata is invalid, or when limits are exceeded. A 404 means the supplied denialCaseId does not resolve in the authenticated organization. Retrying unchanged will not perform extraction.\n\n### Error notes\n- 400 can mean missing safety flag, invalid filename, or file size outside 1 byte through 10 MiB.\n- 404 can mean the optional denialCaseId is missing or outside the authenticated organization.\n- Do not describe retries as eventually performing OCR; this public endpoint is validation-only/dry-run.\n","tags":["Denial Management"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"denialCaseId":{"type":"string","minLength":1,"description":"Optional QuickRCM DenialCase identifier to validate against the authenticated organization."},"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Required display filename for the planned denial document. Keep examples synthetic and avoid PHI in filenames."},"fileSizeBytes":{"type":"integer","minimum":1,"maximum":10485760,"description":"Required planned file size in bytes. The public schema allows 1 through 10485760 bytes."},"validateOnly":{"type":"boolean","description":"Safety flag indicating that the request should only be validated."},"dryRun":{"type":"boolean","description":"Safety flag indicating that the request should be simulated without extraction or queueing."}},"required":["fileName","fileSizeBytes"]},"example":{"fileName":"Example extract_denial_document","fileSizeBytes":1,"denialCaseId":"00000000-0000-4000-8000-000000000001","validateOnly":true,"dryRun":true}}},"description":"`fileName` is required and capped at 255 characters. `fileSizeBytes` is required, must be at least 1 byte, and is capped at 10 MiB. At least one of `validateOnly` or `dryRun` must be true. Do not send file bytes, signed URLs, S3 keys, OCR text, transcripts, raw payer documents, or extracted vendor payloads."},"responses":{"200":{"description":"Extraction request validated without external processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["validateOnly","dryRun"]},"extractionPerformed":{"type":"boolean","enum":[false]},"queued":{"type":"boolean","enum":[false]},"denialCaseId":{"type":["string","null"]},"fileName":{"type":"string"},"fileSizeBytes":{"type":"integer","minimum":1}},"required":["mode","extractionPerformed","queued","denialCaseId","fileName","fileSizeBytes"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"validateOnly","extractionPerformed":false,"queued":false,"denialCaseId":"00000000-0000-4000-8000-000000000001","fileName":"Example extract_denial_document","fileSizeBytes":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Denial case not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/find-patient":{"post":{"operationId":"findEhrPatientByDemographics","summary":"Find EHR patient by demographics","description":"Finds one local QuickRCM patient ID by exact trimmed first name, exact trimmed last name, and date-of-birth day within the organization selected by the bearer API key.\n\n### When to use\nUse this endpoint when an integration has patient demographics and needs the QuickRCM patient identifier before listing appointments, creating coverage, or reconciling scheduling data.\n\n### Before calling\nAuthenticate with an API key that has `ehr:read` or `ehr:write`. Normalize names and send a non-empty `dob` value as `YYYY-MM-DD` or another ISO date string accepted by the public schema.\n\n### Request guidance\n`firstName` and `lastName` are trimmed strings from 1 to 100 characters. `dob` is interpreted as a UTC day range, so callers should send a stable date-only value instead of a local-time timestamp.\n\n### Request notes\n- Do not send `organizationId`; tenant context comes from the API key.\n- The lookup trims names but does not perform fuzzy matching.\n- Avoid logging raw demographic search bodies because they contain PHI.\n- This endpoint is narrower than create/bulk duplicate detection: it does not use MRN and should not be documented as fuzzy or case-insensitive search.\n\n### Response semantics\nA 200 response returns only `data.patientId` and `meta.organizationId`. A 404 response means no patient matched those demographics inside the authenticated organization; it does not distinguish a missing patient from a patient that belongs to another tenant.\n\n### Response notes\n- `data.patientId` is a local QuickRCM identifier, not an external EHR MRN.\n- The response does not include patient demographics, address, contacts, insurance, or appointment details.\n- Use the patient appointment list endpoint when appointment context is needed.\n\n### Errors and retries\nTreat 400 as invalid demographics or date input, 401 as missing or invalid bearer credentials, 403 as tenant authorization failure, 404 as not found in the authenticated organization, and 429 as a backoff signal. Retry only transient 5xx responses.\n\n### Error notes\n- 400 can include field-level validation messages such as invalid `dob`.\n- 404 is tenant-safe and should not be used to infer cross-organization existence.\n- 429 should be retried with client-side backoff rather than tight polling.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100,"description":"Patient given name to match after trimming. Maximum length is 100 characters."},"lastName":{"type":"string","minLength":1,"maxLength":100,"description":"Patient family name to match after trimming. Maximum length is 100 characters."},"dob":{"type":"string","minLength":1,"description":"Patient date of birth. Send `YYYY-MM-DD` for deterministic UTC day matching."}},"required":["firstName","lastName","dob"]},"example":{"firstName":"John","lastName":"Smith","dob":"1984-03-22"}}},"description":"`firstName` and `lastName` are trimmed strings from 1 to 100 characters. `dob` is interpreted as a UTC day range, so callers should send a stable date-only value instead of a local-time timestamp."},"responses":{"200":{"description":"Patient ID for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"patientId":{"type":"string"}},"required":["patientId"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"patientId":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/patients/{patientId}/appointments":{"get":{"operationId":"listEhrPatientAppointments","summary":"List EHR patient appointments","description":"Lists local appointment summaries for one patient after first verifying the patient belongs to the authenticated organization.\n\n### When to use\nUse this endpoint to show a patient's QuickRCM appointment timeline, reconcile scheduling changes, or retrieve appointment IDs before updating an appointment or queuing an appointment eligibility check.\n\n### Before calling\nAuthenticate with an API key that has `ehr:read` or `ehr:write`. Confirm you have the QuickRCM `patientId`; the endpoint does not search by MRN or demographics.\n\n### Request guidance\n`patientId` is required in the path. Use `skip` from 0 to 10000 and `take` from 1 to 100; results are ordered by `startTime` descending.\n\n### Request notes\n- `take` defaults to 50 and is capped at 100.\n- `skip` defaults to 0 and is capped at 10000.\n- The API key selects the organization; do not send a public tenant selector.\n\n### Response semantics\nThe response returns `data.appointments`, `skip`, `take`, and `meta.organizationId`. Appointment rows include local scheduling identifiers, start/end timestamps, status, appointment type, nullable facility/provider IDs, and timestamps.\n\n### Response notes\n- Appointment summaries are local QuickRCM records, not external EHR visit resources.\n- Rows do not include clinical notes, patient address/contact JSON, coverage details, or payer payloads.\n- `facilityId` and `providerId` may be null.\n\n### Errors and retries\nTreat 400 as invalid path or pagination input, 401/403 as credential or authorization issues, 404 as patient not found in the authenticated organization, and 429 as rate limiting. Retry transient 5xx responses with normal backoff.\n\n### Error notes\n- 404 is returned before listing appointments when the patient is not owned by the authenticated organization.\n- Do not retry malformed pagination unchanged.\n- Use backoff for 429 and transient 5xx responses.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"patientId","in":"path","description":"QuickRCM patient identifier from the path. The patient must belong to the API key organization."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"skip","in":"query","description":"Zero-based number of appointment rows to skip. Defaults to 0 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"take","in":"query","description":"Maximum appointment rows to return. Defaults to 50 and cannot exceed 100."}],"responses":{"200":{"description":"Appointment summaries for one organization-scoped patient.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appointments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"status":{"type":"string"},"appointmentType":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"providerId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","startTime","endTime","status","appointmentType","facilityId","providerId","createdAt","updatedAt"]}},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["appointments","skip","take"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appointments":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","startTime":"2026-06-08T10:15:30Z","endTime":"2026-06-08T10:15:30Z","status":"active","appointmentType":"example-appointmenttype","facilityId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"skip":1,"take":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/appointments":{"post":{"operationId":"createEhrAppointment","summary":"Create EHR appointment","description":"Creates a local QuickRCM appointment for an organization-scoped patient and returns the sanitized appointment summary.\n\n### When to use\nUse this endpoint when an external scheduler or intake system needs to create an appointment in QuickRCM before downstream pre-registration, eligibility, prior authorization, or denial-prevention workflows.\n\n### Before calling\nAuthenticate with an API key that has `ehr:write`. Create or locate the QuickRCM patient first, then send ISO date-time values where `endTime` is after `startTime`.\n\n### Request guidance\n`patientId`, `startTime`, `endTime`, and `status` are required. `appointmentType` is optional and nullable. The endpoint verifies the patient belongs to the authenticated organization before writing the appointment.\n\n### Request notes\n- Use ISO date-time strings for `startTime` and `endTime`.\n- `status` is a caller-provided local status string capped at 60 characters.\n- `appointmentType` is a caller-provided local label capped at 120 characters.\n\n### Response semantics\nA 201 response returns the created local appointment summary and `meta.organizationId`. The create handler stores new public appointments with null facility/provider metadata unless other internal workflows later update those fields. It may run internal pre-registration prevention checks after the write, but the public response remains the appointment summary.\n\n### Response notes\n- The response is local QuickRCM scheduling state, not confirmation from an external EHR.\n- New public appointments set nullable facility/provider metadata to null unless later updated by another workflow.\n- The response omits patient demographics and coverage details.\n\n### Errors and retries\nTreat 400 as invalid body input or an appointment interval where `endTime` is not after `startTime`, 401/403 as credential or tenant authorization issues, 404 as patient not found, and 429 as rate limiting. If a create request times out, reconcile by listing appointments for the patient before retrying.\n\n### Error notes\n- 400 is returned when the appointment interval is zero length or inverted.\n- 404 means the submitted `patientId` is not found in the authenticated organization.\n- 429 should be retried with backoff.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"QuickRCM patient identifier that must belong to the authenticated organization."},"startTime":{"type":"string","format":"date-time","description":"Appointment start timestamp as an ISO date-time string."},"endTime":{"type":"string","format":"date-time","description":"Appointment end timestamp as an ISO date-time string. Must be after `startTime`."},"status":{"type":"string","minLength":1,"maxLength":60,"description":"Local appointment status string. Maximum length is 60 characters."},"appointmentType":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional local appointment type label. Send null to omit the label."}},"required":["patientId","startTime","endTime","status"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","startTime":"2026-06-08T10:15:30Z","endTime":"2026-06-08T10:15:30Z","status":"active","appointmentType":"example-appointmenttype"}}},"description":"`patientId`, `startTime`, `endTime`, and `status` are required. `appointmentType` is optional and nullable. The endpoint verifies the patient belongs to the authenticated organization before writing the appointment."},"responses":{"201":{"description":"Created appointment summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appointment":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"status":{"type":"string"},"appointmentType":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"providerId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","startTime","endTime","status","appointmentType","facilityId","providerId","createdAt","updatedAt"]}},"required":["appointment"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appointment":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","startTime":"2026-06-08T10:15:30Z","endTime":"2026-06-08T10:15:30Z","status":"active","appointmentType":"example-appointmenttype","facilityId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/patients":{"post":{"operationId":"createEhrPatient","summary":"Create EHR patient","description":"Creates a local QuickRCM patient in the authenticated organization using a database-only write and duplicate detection on demographics and MRN.\n\n### When to use\nUse this endpoint to register a patient in QuickRCM before creating appointments, insurance records, or downstream RCM workflow records.\n\n### Before calling\nAuthenticate with an API key that has `ehr:write`. Prepare trimmed demographic values and decide whether `mrn`, `address`, or `contacts` should be stored; optional address/contact JSON inputs are not returned in the public patient summary.\n\n### Request guidance\n`firstName`, `lastName`, and `dob` are required. `gender`, `mrn`, `address`, and `contacts` are optional and nullable. A matching existing patient can return 200 with `idempotent: true`; an MRN conflict with different demographics returns 409.\n\n### Request notes\n- `dob` should be sent as `YYYY-MM-DD` for stable storage.\n- `mrn` is optional but participates in duplicate detection when supplied.\n- `address` and `contacts` are accepted as JSON objects or null but are intentionally omitted from the public response.\n- Duplicate detection is broader than find-by-demographics: it can match case-insensitive demographics and the supplied MRN, then returns idempotent success or a conflict depending on whether the matched records agree.\n\n### Response semantics\nA 201 response returns the created sanitized patient summary. A 200 response with `data.idempotent: true` returns the existing matched patient summary. Public patient summaries include identifiers, name, date of birth, gender, MRN, and timestamps, but omit address and contact JSON.\n\n### Response notes\n- `data.idempotent` appears only when an existing patient is returned.\n- `dob` is serialized as a date-only string.\n- The response does not include insurance, appointments, address JSON, or contact JSON.\n\n### Errors and retries\nTreat 400 as invalid field input, 401/403 as credential or authorization issues, 409 as a duplicate patient conflict requiring operator or source-system reconciliation, and 429 as rate limiting. Reconcile by demographics or MRN before retrying after ambiguous timeouts.\n\n### Error notes\n- 409 indicates a duplicate/MRN conflict rather than a transient failure.\n- 400 can include validation errors for required names or invalid date input.\n- Do not retry 409 unchanged.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100,"description":"Patient given name stored after trimming. Maximum length is 100 characters."},"lastName":{"type":"string","minLength":1,"maxLength":100,"description":"Patient family name stored after trimming. Maximum length is 100 characters."},"dob":{"type":"string","minLength":1,"description":"Patient date of birth. Send `YYYY-MM-DD`; public responses serialize it as a date-only string."},"gender":{"type":["string","null"],"minLength":1,"maxLength":60,"description":"Optional caller-provided gender value. Maximum length is 60 characters when present."},"mrn":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional Medical Record Number for the patient within the organization. Maximum length is 120 characters."},"address":{"type":["object","null"],"additionalProperties":{},"description":"Optional JSON object for local patient address details. This field is stored but not returned by public patient summaries."},"contacts":{"type":["object","null"],"additionalProperties":{},"description":"Optional JSON object for local patient contact details. This field is stored but not returned by public patient summaries."}},"required":["firstName","lastName","dob"]},"example":{"firstName":"John","lastName":"Smith","dob":"1984-03-22","gender":"example-gender","mrn":"example-mrn","address":{},"contacts":{}}}},"description":"`firstName`, `lastName`, and `dob` are required. `gender`, `mrn`, `address`, and `contacts` are optional and nullable. A matching existing patient can return 200 with `idempotent: true`; an MRN conflict with different demographics returns 409."},"responses":{"200":{"description":"Existing idempotent patient summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"patient":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"dob":{"type":"string"},"gender":{"type":["string","null"]},"mrn":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","firstName","lastName","dob","gender","mrn","createdAt","updatedAt"]},"idempotent":{"type":"boolean"}},"required":["patient"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"patient":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","dob":"1984-03-22","gender":"example-gender","mrn":"example-mrn","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"idempotent":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"201":{"description":"Created patient summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"patient":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"dob":{"type":"string"},"gender":{"type":["string","null"]},"mrn":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","firstName","lastName","dob","gender","mrn","createdAt","updatedAt"]},"idempotent":{"type":"boolean"}},"required":["patient"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"patient":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","dob":"1984-03-22","gender":"example-gender","mrn":"example-mrn","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"idempotent":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"409":{"description":"Patient duplicate conflict.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/patients/{patientId}":{"put":{"operationId":"updateEhrPatient","summary":"Update EHR patient","description":"Updates safe local patient demographic fields after verifying the patient belongs to the authenticated organization.\n\n### When to use\nUse this endpoint when a connected registration, scheduling, or patient-management system needs to correct QuickRCM's local patient demographics or MRN.\n\n### Before calling\nAuthenticate with an API key that has `ehr:write`. Fetch or store the QuickRCM `patientId`, and send only fields that should change.\n\n### Request guidance\n`patientId` is required in the path. The request body must contain at least one supported patient field. Updating `mrn` checks for another patient in the same organization using that MRN and returns 409 on conflict.\n\n### Request notes\n- At least one body field must be provided.\n- Send null for nullable fields such as `gender`, `mrn`, `address`, or `contacts` when clearing is intended.\n- The API key selects the organization; `patientId` alone is not enough to access cross-tenant data.\n- When updating MRN, the endpoint checks for another same-organization patient already using the requested MRN before writing.\n\n### Response semantics\nA 200 response returns the sanitized updated patient summary and `meta.organizationId`. Public summaries omit address and contact JSON even when those fields were updated.\n\n### Response notes\n- The response includes the updated public patient summary.\n- Address and contacts are not returned by the public schema.\n- No appointment, insurance, or external EHR payload is returned.\n\n### Errors and retries\nTreat 400 as an empty or invalid update body, 401/403 as credential or tenant authorization issues, 404 as patient not found in the authenticated organization, 409 as a duplicate/MRN conflict, and 429 as rate limiting.\n\n### Error notes\n- 404 is returned for missing or wrong-organization patients.\n- 409 requires source-data reconciliation before retrying.\n- 400 is returned for an empty update object.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"patientId","in":"path","description":"QuickRCM patient identifier from the path. The row must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100,"description":"Optional replacement given name stored after trimming."},"lastName":{"type":"string","minLength":1,"maxLength":100,"description":"Optional replacement family name stored after trimming."},"dob":{"type":"string","minLength":1,"description":"Optional replacement date of birth. Send a date-only value when possible."},"gender":{"type":["string","null"],"minLength":1,"maxLength":60,"description":"Optional replacement or null value for the patient's gender field."},"mrn":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional replacement or null value for the Medical Record Number. Conflicts with another same-tenant patient return 409."},"address":{"type":["object","null"],"additionalProperties":{},"description":"Optional replacement JSON object or null for local address details. Not returned in public summaries."},"contacts":{"type":["object","null"],"additionalProperties":{},"description":"Optional replacement JSON object or null for local contact details. Not returned in public summaries."}}},"example":{"firstName":"John","lastName":"Smith","dob":"1984-03-22","gender":"example-gender","mrn":"example-mrn","address":{},"contacts":{}}}},"description":"`patientId` is required in the path. The request body must contain at least one supported patient field. Updating `mrn` checks for another patient in the same organization using that MRN and returns 409 on conflict."},"responses":{"200":{"description":"Updated patient summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"patient":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"dob":{"type":"string"},"gender":{"type":["string","null"]},"mrn":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","firstName","lastName","dob","gender","mrn","createdAt","updatedAt"]}},"required":["patient"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"patient":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","dob":"1984-03-22","gender":"example-gender","mrn":"example-mrn","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Patient duplicate conflict.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/patients/{patientId}/insurances":{"post":{"operationId":"createEhrPatientInsurance","summary":"Create EHR patient insurance","description":"Creates a local patient insurance record for an organization-scoped patient after resolving or creating the tenant payer configuration.\n\n### When to use\nUse this endpoint to add coverage data needed for appointment eligibility, prior authorization, claims, and patient billing workflows.\n\n### Before calling\nAuthenticate with an API key that has `ehr:write`. Confirm the QuickRCM `patientId` belongs to the target patient and send payer/member details from a trusted source.\n\n### Request guidance\n`patientId` is required in the path. `payerId`, `memberId`, and `relationship` are required in the body. `priority` defaults to 1 and is constrained from 1 to 10. Effective and expiration dates accept date-only or ISO date strings.\n\n### Request notes\n- `payerId` is an organization payer identifier used to resolve a local payer configuration.\n- `payerName` can update placeholder payer display names when a payer configuration is resolved.\n- Do not log member IDs, policy numbers, or group numbers.\n\n### Response semantics\nA 201 response returns the created sanitized insurance summary. A 200 response with `data.idempotent: true` means a same-patient, same-member, same-payer insurance row already existed and was returned. The response is local coverage state, not eligibility verification.\n\n### Response notes\n- `data.insurance.payer` contains sanitized payer ID/name metadata, not raw payer payloads.\n- `idempotent` appears only when an existing matching insurance record is returned.\n- The response is local QuickRCM coverage state, not eligibility verification.\n\n### Errors and retries\nTreat 400 as invalid coverage input, 401/403 as credential or tenant authorization issues, 404 as patient not found, and 429 as rate limiting. After an ambiguous timeout, search or re-create carefully because the endpoint can be idempotent for same patient/member/payer combinations.\n\n### Error notes\n- 404 means the patient path ID was not found in the authenticated organization.\n- 400 can indicate invalid date, missing required payer/member fields, or priority outside 1-10.\n- 429 should be retried with backoff.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"patientId","in":"path","description":"QuickRCM patient identifier from the path. The patient must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payerId":{"type":"string","minLength":1,"maxLength":120,"description":"Organization payer identifier used to resolve or create a local payer configuration."},"payerName":{"type":"string","minLength":1,"maxLength":200,"description":"Optional payer display name. May fill placeholder payer metadata during payer-config resolution."},"memberId":{"type":"string","minLength":1,"maxLength":120,"description":"Coverage member/subscriber identifier. Treat as sensitive coverage data."},"groupNumber":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional coverage group number. Treat as sensitive coverage data."},"policyNumber":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional coverage policy number. Treat as sensitive coverage data."},"relationship":{"type":"string","minLength":1,"maxLength":60,"description":"Patient-to-subscriber relationship label stored on the local insurance row."},"relationshipCode":{"type":["string","null"],"minLength":1,"maxLength":20,"description":"Optional patient-to-subscriber relationship code."},"priority":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Coverage priority from 1 to 10. Lower values are considered first when eligibility queueing auto-selects insurance."},"effectiveDate":{"type":["string","null"],"minLength":1,"description":"Optional coverage effective date returned as a date-only string or null."},"expirationDate":{"type":["string","null"],"minLength":1,"description":"Optional coverage expiration date returned as a date-only string or null."}},"required":["payerId","memberId","relationship"]},"example":{"payerId":"87726","memberId":"W123456789","relationship":"example-relationship","payerName":"Example ehr_patient_insurance","groupNumber":"example-groupnumber","policyNumber":"example-policynumber","relationshipCode":"example-relationshipcode","priority":1,"effectiveDate":"2026-06-08","expirationDate":"2026-06-08"}}},"description":"`patientId` is required in the path. `payerId`, `memberId`, and `relationship` are required in the body. `priority` defaults to 1 and is constrained from 1 to 10. Effective and expiration dates accept date-only or ISO date strings."},"responses":{"200":{"description":"Existing idempotent patient insurance summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"insurance":{"type":"object","properties":{"id":{"type":"string"},"patientId":{"type":"string"},"payerConfigId":{"type":["string","null"]},"memberId":{"type":"string"},"groupNumber":{"type":["string","null"]},"policyNumber":{"type":["string","null"]},"relationship":{"type":"string"},"relationshipCode":{"type":["string","null"]},"priority":{"type":"integer"},"effectiveDate":{"type":["string","null"]},"expirationDate":{"type":["string","null"]},"payer":{"type":["object","null"],"properties":{"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["payerId","payerName"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","patientId","payerConfigId","memberId","groupNumber","policyNumber","relationship","relationshipCode","priority","effectiveDate","expirationDate","payer","createdAt","updatedAt"]},"idempotent":{"type":"boolean"}},"required":["insurance"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"insurance":{"id":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","memberId":"W123456789","groupNumber":"example-groupnumber","policyNumber":"example-policynumber","relationship":"example-relationship","relationshipCode":"example-relationshipcode","priority":1,"effectiveDate":"2026-06-08","expirationDate":"2026-06-08","payer":{"payerId":"87726","payerName":"Example ehr_patient_insurance"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"idempotent":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"201":{"description":"Created patient insurance summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"insurance":{"type":"object","properties":{"id":{"type":"string"},"patientId":{"type":"string"},"payerConfigId":{"type":["string","null"]},"memberId":{"type":"string"},"groupNumber":{"type":["string","null"]},"policyNumber":{"type":["string","null"]},"relationship":{"type":"string"},"relationshipCode":{"type":["string","null"]},"priority":{"type":"integer"},"effectiveDate":{"type":["string","null"]},"expirationDate":{"type":["string","null"]},"payer":{"type":["object","null"],"properties":{"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["payerId","payerName"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","patientId","payerConfigId","memberId","groupNumber","policyNumber","relationship","relationshipCode","priority","effectiveDate","expirationDate","payer","createdAt","updatedAt"]},"idempotent":{"type":"boolean"}},"required":["insurance"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"insurance":{"id":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","memberId":"W123456789","groupNumber":"example-groupnumber","policyNumber":"example-policynumber","relationship":"example-relationship","relationshipCode":"example-relationshipcode","priority":1,"effectiveDate":"2026-06-08","expirationDate":"2026-06-08","payer":{"payerId":"87726","payerName":"Example ehr_patient_insurance"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"idempotent":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/patients/{patientId}/insurances/{insuranceId}":{"put":{"operationId":"updateEhrPatientInsurance","summary":"Update EHR patient insurance","description":"Updates a local patient insurance record after proving both the patient and insurance row belong to the authenticated organization.\n\n### When to use\nUse this endpoint when an integration needs to correct payer configuration, member details, relationship metadata, priority, or coverage dates for an existing QuickRCM insurance row.\n\n### Before calling\nAuthenticate with an API key that has `ehr:write`. Confirm the QuickRCM `patientId` and `insuranceId`, and send at least one effective insurance field.\n\n### Request guidance\n`patientId` and `insuranceId` are required path parameters. The body must include at least one update field that changes the insurance row. `payerName` only participates when `payerId` is included for payer-config resolution; a `payerName`-only body is accepted by schema shape but produces no insurance-row update and should be documented as an empty/no-op update that returns 400.\n\n### Request notes\n- `payerId` triggers payer-config lookup or creation; `payerName` is only meaningful alongside `payerId`.\n- Send null for nullable fields such as `groupNumber`, `policyNumber`, `relationshipCode`, `effectiveDate`, or `expirationDate` when clearing is intended.\n- Avoid logging member, group, or policy values.\n- `payerName` is payer-config display metadata; when sent without `payerId`, it does not by itself identify a payer configuration to update.\n\n### Response semantics\nA 200 response returns the updated sanitized insurance summary and `meta.organizationId`. The endpoint scopes the insurance lookup through the owning patient before updating.\n\n### Response notes\n- The response includes sanitized local insurance state and payer display metadata.\n- No raw payer payload, eligibility response, or clearinghouse transaction is returned.\n- `payerConfigId` can change when `payerId` resolves to another tenant payer configuration.\n\n### Errors and retries\nTreat 400 as an empty/no-op or invalid update, 401/403 as credential or tenant authorization issues, 404 as patient or insurance not found in the authenticated organization, and 429 as rate limiting.\n\n### Error notes\n- 404 is tenant-safe and is returned when either the patient or insurance row is not accessible in the authenticated organization.\n- 400 is expected for a body that only includes `payerName` without `payerId` because no persisted insurance field changes.\n- Do not retry malformed dates or empty updates unchanged.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"patientId","in":"path","description":"QuickRCM patient identifier from the path."},{"schema":{"type":"string","minLength":1},"required":true,"name":"insuranceId","in":"path","description":"QuickRCM patient insurance identifier from the path. The row must belong to `patientId` and the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payerId":{"type":"string","minLength":1,"maxLength":120,"description":"Optional replacement organization payer identifier. When supplied, it resolves or creates the local payer configuration."},"payerName":{"type":"string","minLength":1,"maxLength":200,"description":"Optional payer display name used only during payer-config resolution when `payerId` is present."},"memberId":{"type":"string","minLength":1,"maxLength":120,"description":"Optional replacement coverage member/subscriber identifier."},"groupNumber":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional replacement or null coverage group number."},"policyNumber":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional replacement or null coverage policy number."},"relationship":{"type":"string","minLength":1,"maxLength":60,"description":"Optional replacement patient-to-subscriber relationship label."},"relationshipCode":{"type":["string","null"],"minLength":1,"maxLength":20,"description":"Optional replacement or null relationship code."},"priority":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Optional replacement priority from 1 to 10."},"effectiveDate":{"type":["string","null"],"minLength":1,"description":"Optional replacement or null coverage effective date."},"expirationDate":{"type":["string","null"],"minLength":1,"description":"Optional replacement or null coverage expiration date."}}},"example":{"payerId":"87726","payerName":"Example ehr_patient_insurance","memberId":"W123456789","groupNumber":"example-groupnumber","policyNumber":"example-policynumber","relationship":"example-relationship","relationshipCode":"example-relationshipcode","priority":1}}},"description":"`patientId` and `insuranceId` are required path parameters. The body must include at least one update field that changes the insurance row. `payerName` only participates when `payerId` is included for payer-config resolution; a `payerName`-only body is accepted by schema shape but produces no insurance-row update and should be documented as an empty/no-op update that returns 400."},"responses":{"200":{"description":"Updated patient insurance summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"insurance":{"type":"object","properties":{"id":{"type":"string"},"patientId":{"type":"string"},"payerConfigId":{"type":["string","null"]},"memberId":{"type":"string"},"groupNumber":{"type":["string","null"]},"policyNumber":{"type":["string","null"]},"relationship":{"type":"string"},"relationshipCode":{"type":["string","null"]},"priority":{"type":"integer"},"effectiveDate":{"type":["string","null"]},"expirationDate":{"type":["string","null"]},"payer":{"type":["object","null"],"properties":{"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["payerId","payerName"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","patientId","payerConfigId","memberId","groupNumber","policyNumber","relationship","relationshipCode","priority","effectiveDate","expirationDate","payer","createdAt","updatedAt"]}},"required":["insurance"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"insurance":{"id":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","memberId":"W123456789","groupNumber":"example-groupnumber","policyNumber":"example-policynumber","relationship":"example-relationship","relationshipCode":"example-relationshipcode","priority":1,"effectiveDate":"2026-06-08","expirationDate":"2026-06-08","payer":{"payerId":"87726","payerName":"Example ehr_patient_insurance"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Insurance not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/patients/bulk":{"post":{"operationId":"bulkCreateEhrPatients","summary":"Bulk create EHR patients","description":"Creates up to 100 local QuickRCM patient rows from inline JSON and returns per-row counts plus sanitized patient summaries.\n\n### When to use\nUse this endpoint for small, API-driven patient backfills or incremental registration imports when a caller can send structured JSON directly.\n\n### Before calling\nAuthenticate with an API key that has `ehr:write`. Split large imports into batches of 100 or fewer patients and use synthetic or redacted data in logs and test fixtures.\n\n### Request guidance\n`patients` must contain 1 to 100 patient objects using the same patient fields as create patient. For each row, the handler checks for an existing same-organization patient matching the row demographics or the supplied MRN. Matching rows are skipped and returned in `patients`; new rows are created. This bulk skip behavior differs from single create, which can return 409 when MRN and demographics identify different patients.\n\n### Request notes\n- This endpoint does not accept CSV files, presigned uploads, S3 keys, or background-worker job payloads.\n- Rows are skipped when the authenticated organization already has a patient matching demographics or the supplied MRN.\n- Address and contact JSON can be stored but are omitted from returned public patient summaries.\n- Bulk duplicate matching is broader than find-by-demographics because it can match same-organization demographics case-insensitively and can also use supplied MRN.\n\n### Response semantics\nA 201 response means at least one row was created; a 200 response means the batch completed with no new rows. The response includes `created`, `skipped`, `failed`, sanitized `patients`, row-level `errors`, `meta.organizationId`, and `meta.mode: SAFE_WRITE_DB_ONLY`.\n\n### Response notes\n- `meta.mode` is `SAFE_WRITE_DB_ONLY`.\n- `created + skipped + failed` should equal the number of input rows.\n- `errors[].row` uses a 1-based input row number.\n\n### Errors and retries\nTreat top-level 400 as an invalid batch shape, 401/403 as credential or tenant authorization issues, and 429 as rate limiting. Row-level failures appear in `data.errors` while successful or skipped rows can still be returned. Reconcile by MRN and demographics before retrying failed rows.\n\n### Error notes\n- Top-level schema errors fail the request before row processing.\n- Row-level errors are sanitized messages and should not include raw PHI-heavy payloads.\n- Do not retry a full batch blindly after a partial success; use returned counts and row errors.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patients":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100,"description":"Patient given name for the bulk row."},"lastName":{"type":"string","minLength":1,"maxLength":100,"description":"Patient family name for the bulk row."},"dob":{"type":"string","minLength":1,"description":"Patient date of birth for the bulk row. Send `YYYY-MM-DD` when possible."},"gender":{"type":["string","null"],"minLength":1,"maxLength":60,"description":"Optional gender value for the bulk row."},"mrn":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional Medical Record Number for the bulk row."},"address":{"type":["object","null"],"additionalProperties":{},"description":"Optional address JSON object for the bulk row. Not returned in public summaries."},"contacts":{"type":["object","null"],"additionalProperties":{},"description":"Optional contact JSON object for the bulk row. Not returned in public summaries."}},"required":["firstName","lastName","dob"]},"minItems":1,"maxItems":100,"description":"Array of 1 to 100 patient objects to create or skip."}},"required":["patients"]},"example":{"patients":[{"firstName":"John","lastName":"Smith","dob":"1984-03-22","gender":"example-gender","mrn":"example-mrn","address":{},"contacts":{}}]}}},"description":"`patients` must contain 1 to 100 patient objects using the same patient fields as create patient. For each row, the handler checks for an existing same-organization patient matching the row demographics or the supplied MRN. Matching rows are skipped and returned in `patients`; new rows are created. This bulk skip behavior differs from single create, which can return 409 when MRN and demographics identify different patients."},"responses":{"200":{"description":"Bulk patient import result with no new rows.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"created":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"},"patients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"dob":{"type":"string"},"gender":{"type":["string","null"]},"mrn":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","firstName","lastName","dob","gender","mrn","createdAt","updatedAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"message":{"type":"string"}},"required":["row","message"]}}},"required":["created","skipped","failed","patients","errors"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]}},"required":["organizationId","mode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"created":1,"skipped":1,"failed":1,"patients":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","dob":"1984-03-22","gender":"example-gender","mrn":"example-mrn","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"errors":[{"row":1,"message":"Request failed"}]},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","mode":"SAFE_WRITE_DB_ONLY"}}}}},"201":{"description":"Bulk patient import result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"created":{"type":"integer"},"skipped":{"type":"integer"},"failed":{"type":"integer"},"patients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"dob":{"type":"string"},"gender":{"type":["string","null"]},"mrn":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","firstName","lastName","dob","gender","mrn","createdAt","updatedAt"]}},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"message":{"type":"string"}},"required":["row","message"]}}},"required":["created","skipped","failed","patients","errors"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]}},"required":["organizationId","mode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"created":1,"skipped":1,"failed":1,"patients":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","dob":"1984-03-22","gender":"example-gender","mrn":"example-mrn","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"errors":[{"row":1,"message":"Request failed"}]},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","mode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/appointments/{appointmentId}":{"put":{"operationId":"updateEhrAppointment","summary":"Update EHR appointment","description":"Updates local appointment scheduling fields after an organization-scoped appointment lookup.\n\n### When to use\nUse this endpoint to reschedule, reassign to another tenant-scoped patient, update local status, or change an appointment type label in QuickRCM.\n\n### Before calling\nAuthenticate with an API key that has `ehr:write`. Load the current appointment state if only one side of the time interval will change, because the resulting interval must remain valid.\n\n### Request guidance\n`appointmentId` is required in the path. The body must contain at least one supported field. If `patientId` is supplied, the new patient must belong to the authenticated organization. If either `startTime` or `endTime` changes, the resulting end time must be after the resulting start time.\n\n### Request notes\n- At least one body field must be provided.\n- `appointmentType` can be null to clear the local label.\n- Use ISO date-time strings for time fields.\n\n### Response semantics\nA 200 response returns the updated local appointment summary and `meta.organizationId`. The handler may run internal pre-registration prevention checks after the appointment update, but does not return those internal work items.\n\n### Response notes\n- The response is a local QuickRCM appointment summary.\n- The response does not include patient demographics, coverage details, or prevention work items.\n- `facilityId` and `providerId` may be null.\n\n### Errors and retries\nTreat 400 as an empty or invalid update or invalid resulting interval, 401/403 as credential or tenant authorization issues, 404 as appointment or replacement patient not found in the authenticated organization, and 429 as rate limiting.\n\n### Error notes\n- 400 is returned when the resulting interval has `endTime` at or before `startTime`.\n- 404 is returned when the appointment ID is missing or wrong-tenant.\n- If a timeout occurs, fetch the appointment list before retrying a potentially applied update.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appointmentId","in":"path","description":"QuickRCM appointment identifier from the path. The row must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"Optional replacement QuickRCM patient identifier. The patient must belong to the authenticated organization."},"startTime":{"type":"string","format":"date-time","description":"Optional replacement appointment start timestamp as an ISO date-time string."},"endTime":{"type":"string","format":"date-time","description":"Optional replacement appointment end timestamp as an ISO date-time string. The resulting value must be after the resulting start time."},"status":{"type":"string","minLength":1,"maxLength":60,"description":"Optional replacement local appointment status string."},"appointmentType":{"type":["string","null"],"minLength":1,"maxLength":200,"description":"Optional replacement or null local appointment type label."}}},"example":{"patientId":"00000000-0000-4000-8000-000000000001","startTime":"2026-06-08T10:15:30Z","endTime":"2026-06-08T10:15:30Z","status":"active","appointmentType":"example-appointmenttype"}}},"description":"`appointmentId` is required in the path. The body must contain at least one supported field. If `patientId` is supplied, the new patient must belong to the authenticated organization. If either `startTime` or `endTime` changes, the resulting end time must be after the resulting start time."},"responses":{"200":{"description":"Updated appointment summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appointment":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"status":{"type":"string"},"appointmentType":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"providerId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","startTime","endTime","status","appointmentType","facilityId","providerId","createdAt","updatedAt"]}},"required":["appointment"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appointment":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","startTime":"2026-06-08T10:15:30Z","endTime":"2026-06-08T10:15:30Z","status":"active","appointmentType":"example-appointmenttype","facilityId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appointment not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/appointments/{appointmentId}/status":{"put":{"operationId":"updateEhrAppointmentStatus","summary":"Update EHR appointment status","description":"Updates only the local appointment status after verifying the appointment belongs to the authenticated organization.\n\n### When to use\nUse this endpoint for lightweight status transitions from scheduling, check-in, cancellation, or operational workflow systems when no other appointment fields need to change.\n\n### Before calling\nAuthenticate with an API key that has `ehr:write`. Use the QuickRCM appointment ID and a non-empty status string accepted by the local workflow.\n\n### Request guidance\n`appointmentId` is required in the path and `status` is required in the body. This endpoint does not accept start/end time, patient, or appointment type changes.\n\n### Request notes\n- `status` is trimmed and capped at 60 characters.\n- Use the full appointment update endpoint when changing time, patient, or appointment type.\n- Do not use status text to store clinical notes or PHI-heavy free text.\n\n### Response semantics\nA 200 response returns the updated appointment summary. The handler may run internal pre-registration prevention checks after a status update, but the public response remains appointment state only.\n\n### Response notes\n- The response includes the full public appointment summary after the status update.\n- No external EHR confirmation is included.\n- No prevention work item details are returned.\n\n### Errors and retries\nTreat 400 as invalid status input, 401/403 as credential or tenant authorization issues, 404 as appointment not found in the authenticated organization, and 429 as rate limiting.\n\n### Error notes\n- 404 means the appointment was not found within the authenticated organization.\n- 400 can indicate an empty status.\n- Use backoff for 429 or transient 5xx responses.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appointmentId","in":"path","description":"QuickRCM appointment identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","minLength":1,"maxLength":60,"description":"Required local appointment status string. Maximum length is 60 characters."}},"required":["status"]},"example":{"status":"active"}}},"description":"`appointmentId` is required in the path and `status` is required in the body. This endpoint does not accept start/end time, patient, or appointment type changes."},"responses":{"200":{"description":"Updated appointment status summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appointment":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"status":{"type":"string"},"appointmentType":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"providerId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","startTime","endTime","status","appointmentType","facilityId","providerId","createdAt","updatedAt"]}},"required":["appointment"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appointment":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","startTime":"2026-06-08T10:15:30Z","endTime":"2026-06-08T10:15:30Z","status":"active","appointmentType":"example-appointmenttype","facilityId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appointment not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr/appointments/{appointmentId}/eligibility/check":{"post":{"operationId":"queueEhrAppointmentEligibilityCheck","summary":"Queue appointment eligibility check","description":"Creates a local queued eligibility-check record for an organization-scoped appointment and patient insurance record without calling a payer or clearinghouse synchronously.\n\n### When to use\nUse this endpoint when an integration wants QuickRCM to record an appointment-level eligibility check request for later processing or workflow visibility while keeping the public API call safe and non-vendor-submitting.\n\n### Before calling\nAuthenticate with an API key that has `ehr:write`. Ensure the appointment belongs to the authenticated organization and either supply a patient insurance ID for the appointment's patient or rely on the endpoint to select the first matching insurance by priority.\n\n### Request guidance\n`appointmentId` is required in the path. `queueOnly` is literal `true` and defaults to true; public callers cannot request a live clearinghouse call. `serviceType` defaults to `30`; `dateOfService` defaults to the appointment start date when omitted.\n\n### Request notes\n- This endpoint does not call Availity, Stedi, a payer portal, or an external EHR inline.\n- `queueOnly` must be true; no unsafe live mode is exposed.\n- Do not log member IDs or payer-related coverage identifiers used to select insurance.\n\n### Response semantics\nA 202 response returns a queued local eligibility-check summary plus `meta.mode: SIMULATED_ONLY`. The created row has `status: QUEUED`, `statusCode: null`, and `queueOnly: true`. The response is not payer eligibility, benefits, or clearinghouse acceptance evidence.\n\n### Response notes\n- `meta.mode` is `SIMULATED_ONLY` for this public wrapper.\n- `eligibilityCheck.queueOnly` is always true.\n- `eligibilityCheck.status` is `QUEUED` and `eligibilityCheck.statusCode` is null when the public endpoint creates the row.\n\n### Errors and retries\nTreat 400 as invalid date or request shape, 401/403 as credential or tenant authorization issues, 404 as appointment or patient insurance not found in the authenticated organization, and 429 as rate limiting. Reconcile existing eligibility checks before retrying after ambiguous timeouts.\n\n### Error notes\n- 404 can mean the appointment does not exist in the tenant or no suitable patient insurance record was found.\n- 400 can indicate invalid `dateOfService`.\n- Use client backoff for 429 and normal retry limits for transient 5xx responses.\n","tags":["EHR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appointmentId","in":"path","description":"QuickRCM appointment identifier from the path. The appointment must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientInsuranceId":{"type":"string","minLength":1,"description":"Optional QuickRCM patient insurance identifier. If omitted, the endpoint selects the patient's first matching insurance ordered by priority."},"serviceType":{"type":"string","minLength":1,"maxLength":20,"default":"30","description":"Optional eligibility service type code. Defaults to `30` and is capped at 20 characters."},"dateOfService":{"type":"string","minLength":1,"description":"Optional service date as `YYYY-MM-DD` or an ISO date string. Defaults to the appointment start date and is returned as an ISO date-time string."},"queueOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safe-mode flag. The public endpoint only accepts true and does not call a clearinghouse inline."}}},"example":{"patientInsuranceId":"00000000-0000-4000-8000-000000000001","serviceType":"30","dateOfService":"2026-06-08","queueOnly":true}}},"description":"`appointmentId` is required in the path. `queueOnly` is literal `true` and defaults to true; public callers cannot request a live clearinghouse call. `serviceType` defaults to `30`; `dateOfService` defaults to the appointment start date when omitted."},"responses":{"202":{"description":"Queued local eligibility check summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"eligibilityCheck":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":"string"},"patientInsuranceId":{"type":"string"},"serviceType":{"type":["string","null"]},"dateOfService":{"type":"string","format":"date-time"},"status":{"type":"string"},"statusCode":{"type":["string","null"]},"queueOnly":{"type":"boolean","enum":[true]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","appointmentId","patientInsuranceId","serviceType","dateOfService","status","statusCode","queueOnly","createdAt"]}},"required":["eligibilityCheck"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"mode":{"type":"string","enum":["SIMULATED_ONLY"]}},"required":["organizationId","mode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"eligibilityCheck":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","serviceType":"30","dateOfService":"2026-06-08T10:15:30Z","status":"queued","statusCode":"example-statuscode","queueOnly":true,"createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","mode":"SIMULATED_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appointment or patient insurance not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/config":{"get":{"operationId":"getEhrIntegrationConfig","summary":"Get EHR integration configuration summary","description":"Returns the authenticated organization's sanitized EHR integration configuration summary, or null when no configuration exists.\n\n### When to use\nUse this before rendering integration settings, reconciling an ambiguous config update, deciding whether queue/validation calls have a configured EHR, or showing current local health/config metadata.\n\n### Before calling\nAuthenticate with a tenant-scoped API key that can read EHR Integration data. Do not send organizationId; tenant context comes from the bearer credential.\n\n### Request guidance\nThis endpoint has no request body or filters.\n\n### Request notes\n- No request body is accepted.\n- The API key selects the organization.\n- Use this to confirm current local configuration before retrying ambiguous write calls.\n\n### Response semantics\nHTTP 200 returns `data.config` as a sanitized object or null. Config responses include local ids, vendor/display metadata, health metadata, rate/retry/batch settings, webhook-enabled flag, entityConfigs, and timestamps. They intentionally omit baseUrl, siteId, authType, credential status, credentials, webhook secrets, endpoint URLs, and custom vendor config.\n\n### Response notes\n- `data.config` may be null.\n- `entityConfigs` describes configured local entity sync policy, not a live vendor capability statement.\n- The response may include local organization/config ids but not raw vendor credentials or endpoint URLs.\n\n### Errors and retries\nTreat 401/403 as credential or authorization failures and 429 as a backoff signal. A transient 5xx can be retried with bounded client retries.\n\n### Error notes\n- 401 means bearer authentication is missing or invalid.\n- 403 means the credential/user context cannot read EHR Integration data for the organization.\n- 429 should be retried with backoff.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Sanitized EHR integration configuration for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"config":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"ehrSystem":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","OTHER"]},"ehrDisplayName":{"type":"string"},"ehrVersion":{"type":["string","null"]},"apiPreference":{"type":"string","enum":["STANDARD_REST","FHIR_R4","HYBRID"]},"isActive":{"type":"boolean"},"healthStatus":{"type":"string","enum":["HEALTHY","DEGRADED","DISCONNECTED","UNKNOWN"]},"lastHealthCheckAt":{"type":["string","null"],"format":"date-time"},"rateLimitPerMinute":{"type":"integer","minimum":0},"retryMaxAttempts":{"type":"integer","minimum":0},"retryBackoffMs":{"type":"integer","minimum":0},"syncBatchSize":{"type":"integer","minimum":1},"enableWebhooks":{"type":"boolean"},"entityConfigs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"syncDirection":{"type":"string","enum":["READ_ONLY","WRITE_ONLY","BIDIRECTIONAL","DISABLED"]},"syncStrategy":{"type":"string","enum":["REAL_TIME","SCHEDULED","ON_DEMAND"]},"syncSchedule":{"type":["string","null"]},"sourceOfTruth":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","RCM_PLATFORM","MANUAL"]},"conflictResolution":{"type":"string","enum":["LAST_WRITE_WINS","SOURCE_OF_TRUTH_WINS","MANUAL_QUEUE"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","entityType","syncDirection","syncStrategy","syncSchedule","sourceOfTruth","conflictResolution","isActive","createdAt","updatedAt"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","ehrSystem","ehrDisplayName","ehrVersion","apiPreference","isActive","healthStatus","lastHealthCheckAt","rateLimitPerMinute","retryMaxAttempts","retryBackoffMs","syncBatchSize","enableWebhooks","entityConfigs","createdAt","updatedAt"]}},"required":["config"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"config":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","ehrSystem":"OPENEMR","ehrDisplayName":"Example ehr_integration_config","ehrVersion":"example-ehrversion","apiPreference":"STANDARD_REST","isActive":true,"healthStatus":"HEALTHY","lastHealthCheckAt":"2026-06-08T10:15:30Z","rateLimitPerMinute":1,"retryMaxAttempts":1,"retryBackoffMs":1,"syncBatchSize":1,"enableWebhooks":true,"entityConfigs":[{"id":"00000000-0000-4000-8000-000000000001","entityType":"PATIENT","syncDirection":"READ_ONLY","syncStrategy":"REAL_TIME","syncSchedule":"example-syncschedule","sourceOfTruth":"OPENEMR","conflictResolution":"LAST_WRITE_WINS","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"upsertEhrIntegrationConfig","summary":"Create or update EHR integration configuration","description":"Creates or updates the authenticated organization's local EHR integration configuration using redacted setup metadata.\n\n### When to use\nUse this during onboarding or admin configuration changes to set vendor, base URL, API preference, active flag, retry/rate-limit controls, batch size, webhook-enabled flag, and redacted credential-status indicators.\n\n### Before calling\nCollect non-secret configuration values and decide whether the local config should be active. Do not include raw API keys, client secrets, private keys, JWK contents, webhook secrets, access tokens, refresh tokens, or raw SMART/FHIR responses.\n\n### Request guidance\n`baseUrl` is required and must be a URI. `ehrSystem` defaults to OPENEMR and accepts OPENEMR, EPIC, CERNER, ECLINICALWORKS, ATHENA, MEDITECH, or OTHER. `apiPreference` defaults to HYBRID. `authType` defaults to OAUTH2_CLIENT_CREDENTIALS and accepts OAUTH2_CLIENT_CREDENTIALS, OAUTH2_PASSWORD, or OAUTH2_AUTHORIZATION_CODE. `siteId` is 1-100 characters and defaults to `default`; `ehrVersion` is optional and 1-100 characters. Numeric limits are bounded: `rateLimitPerMinute` 1-600, `retryMaxAttempts` 0-10, `retryBackoffMs` 0-60000, and `syncBatchSize` 1-500. `credentialStatus.scopes` accepts up to 50 non-empty strings. `credentialStatus` accepts flags/scopes and request metadata such as `epicBulkGroupId`; it is not a secret transport.\n\n### Request notes\n- `baseUrl` is required in the request but intentionally omitted from the response.\n- `siteId`, `authType`, and `credentialStatus` are accepted in the request but omitted from sanitized config responses.\n- `credentialStatus.epicBulkGroupId` is request metadata; connection-test responses expose only `epicBulkGroupIdConfigured`.\n- Do not document credential rotation or secret storage behavior unless a separate supported secret-management workflow is cited.\n\n### Response semantics\nHTTP 200 returns the sanitized config after create/update. The response does not prove live EHR connectivity and does not return baseUrl, siteId, authType, credentialStatus, credential values, webhook secrets, endpoint URLs, or custom vendor config.\n\n### Response notes\n- Returns the same sanitized config shape as getEhrIntegrationConfig.\n- Use testEhrConnection only for redacted request-shape validation; use health monitoring for live availability.\n- Vendor enum values do not imply public write support for every vendor/resource.\n\n### Errors and retries\nFix 400 validation errors before retrying. After an ambiguous timeout, call getEhrIntegrationConfig before repeating the upsert to avoid overwriting a successful update with stale values.\n\n### Error notes\n- 400 can indicate an invalid URL, enum, strict-body extra property, or out-of-range numeric setting.\n- 403 means the caller lacks EHR Integration write permission or tenant authorization.\n- Retry 429/5xx with backoff; do not retry malformed payloads unchanged.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ehrSystem":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","OTHER"],"default":"OPENEMR","description":"Configured vendor enum. Defaults to OPENEMR; accepted values are OPENEMR, EPIC, CERNER, ECLINICALWORKS, ATHENA, MEDITECH, and OTHER."},"ehrVersion":{"type":"string","minLength":1,"maxLength":100,"description":"Optional version or environment label, 1-100 characters when supplied. It is returned as nullable metadata, not as a live capability statement."},"baseUrl":{"type":"string","format":"uri","description":"Vendor endpoint base URI accepted in the request. It is sensitive operational metadata and is not returned."},"siteId":{"type":"string","minLength":1,"maxLength":100,"default":"default","description":"Optional site identifier, 1-100 characters, defaulting to default. It is accepted in the request and omitted from sanitized config responses."},"authType":{"type":"string","enum":["OAUTH2_CLIENT_CREDENTIALS","OAUTH2_PASSWORD","OAUTH2_AUTHORIZATION_CODE"],"default":"OAUTH2_CLIENT_CREDENTIALS","description":"OAuth flow metadata. Defaults to OAUTH2_CLIENT_CREDENTIALS; accepted values are OAUTH2_CLIENT_CREDENTIALS, OAUTH2_PASSWORD, and OAUTH2_AUTHORIZATION_CODE. It is not returned in sanitized config responses."},"apiPreference":{"type":"string","enum":["STANDARD_REST","FHIR_R4","HYBRID"],"default":"HYBRID","description":"Configured EHR API mode. Defaults to HYBRID; accepted values are STANDARD_REST, FHIR_R4, and HYBRID."},"credentialStatus":{"type":"object","properties":{"hasClientSecret":{"type":"boolean","default":false},"hasPrivateKey":{"type":"boolean","default":false},"hasJwk":{"type":"boolean","default":false},"tokenUrlConfigured":{"type":"boolean","default":false},"scopes":{"type":"array","items":{"type":"string","minLength":1},"maxItems":50,"default":[],"description":"Array of up to 50 non-empty scope strings used as redacted credential metadata; do not include tokens or secrets."},"epicBulkGroupId":{"type":"string","minLength":1,"description":"Optional request metadata indicating the Epic bulk group id is configured; the public connection-test response returns only a boolean configured flag."}},"default":{},"additionalProperties":false,"description":"Redacted credential metadata flags/scopes. It must not include secret values."},"isActive":{"type":"boolean","default":false,"description":"Schedule active-state boolean. Schedule create defaults to true; pause/resume endpoints also mutate active state."},"rateLimitPerMinute":{"type":"integer","minimum":1,"maximum":600,"default":60,"description":"Local per-minute budget for EHR integration work; accepted range is 1 to 600."},"retryMaxAttempts":{"type":"integer","minimum":0,"maximum":10,"default":3},"retryBackoffMs":{"type":"integer","minimum":0,"maximum":60000,"default":1000},"syncBatchSize":{"type":"integer","minimum":1,"maximum":500,"default":50,"description":"Maximum records per sync batch; accepted range is 1 to 500."},"enableWebhooks":{"type":"boolean","default":false}},"required":["baseUrl"],"additionalProperties":false},"example":{"baseUrl":"https://example.quickintell.com/resource","ehrSystem":"OPENEMR","ehrVersion":"example-ehrversion","siteId":"default","authType":"OAUTH2_CLIENT_CREDENTIALS","apiPreference":"HYBRID","credentialStatus":{},"isActive":false,"rateLimitPerMinute":60}}},"description":"`baseUrl` is required and must be a URI. `ehrSystem` defaults to OPENEMR and accepts OPENEMR, EPIC, CERNER, ECLINICALWORKS, ATHENA, MEDITECH, or OTHER. `apiPreference` defaults to HYBRID. `authType` defaults to OAUTH2_CLIENT_CREDENTIALS and accepts OAUTH2_CLIENT_CREDENTIALS, OAUTH2_PASSWORD, or OAUTH2_AUTHORIZATION_CODE. `siteId` is 1-100 characters and defaults to `default`; `ehrVersion` is optional and 1-100 characters. Numeric limits are bounded: `rateLimitPerMinute` 1-600, `retryMaxAttempts` 0-10, `retryBackoffMs` 0-60000, and `syncBatchSize` 1-500. `credentialStatus.scopes` accepts up to 50 non-empty strings. `credentialStatus` accepts flags/scopes and request metadata such as `epicBulkGroupId`; it is not a secret transport."},"responses":{"200":{"description":"Sanitized EHR integration configuration after create/update.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"config":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"ehrSystem":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","OTHER"]},"ehrDisplayName":{"type":"string"},"ehrVersion":{"type":["string","null"]},"apiPreference":{"type":"string","enum":["STANDARD_REST","FHIR_R4","HYBRID"]},"isActive":{"type":"boolean"},"healthStatus":{"type":"string","enum":["HEALTHY","DEGRADED","DISCONNECTED","UNKNOWN"]},"lastHealthCheckAt":{"type":["string","null"],"format":"date-time"},"rateLimitPerMinute":{"type":"integer","minimum":0},"retryMaxAttempts":{"type":"integer","minimum":0},"retryBackoffMs":{"type":"integer","minimum":0},"syncBatchSize":{"type":"integer","minimum":1},"enableWebhooks":{"type":"boolean"},"entityConfigs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"syncDirection":{"type":"string","enum":["READ_ONLY","WRITE_ONLY","BIDIRECTIONAL","DISABLED"]},"syncStrategy":{"type":"string","enum":["REAL_TIME","SCHEDULED","ON_DEMAND"]},"syncSchedule":{"type":["string","null"]},"sourceOfTruth":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","RCM_PLATFORM","MANUAL"]},"conflictResolution":{"type":"string","enum":["LAST_WRITE_WINS","SOURCE_OF_TRUTH_WINS","MANUAL_QUEUE"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","entityType","syncDirection","syncStrategy","syncSchedule","sourceOfTruth","conflictResolution","isActive","createdAt","updatedAt"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","ehrSystem","ehrDisplayName","ehrVersion","apiPreference","isActive","healthStatus","lastHealthCheckAt","rateLimitPerMinute","retryMaxAttempts","retryBackoffMs","syncBatchSize","enableWebhooks","entityConfigs","createdAt","updatedAt"]}},"required":["config"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"config":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","ehrSystem":"OPENEMR","ehrDisplayName":"Example upsert_ehr_integration_config","ehrVersion":"example-ehrversion","apiPreference":"STANDARD_REST","isActive":true,"healthStatus":"HEALTHY","lastHealthCheckAt":"2026-06-08T10:15:30Z","rateLimitPerMinute":1,"retryMaxAttempts":1,"retryBackoffMs":1,"syncBatchSize":1,"enableWebhooks":true,"entityConfigs":[{"id":"00000000-0000-4000-8000-000000000001","entityType":"PATIENT","syncDirection":"READ_ONLY","syncStrategy":"REAL_TIME","syncSchedule":"example-syncschedule","sourceOfTruth":"OPENEMR","conflictResolution":"LAST_WRITE_WINS","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/sync-logs":{"get":{"operationId":"listEhrSyncLogs","summary":"List EHR sync logs","description":"Lists sanitized EHR sync-log metadata for the authenticated organization with filters for log id, entity type, status, direction, date range, summaryOnly, and pagination.\n\n### When to use\nUse this for integration monitoring, queue reconciliation, audit views, or troubleshooting local sync work without exposing raw EHR payloads.\n\n### Before calling\nChoose the narrowest filters possible. Sync logs can reveal workflow timing and integration state even when payloads are redacted.\n\n### Request guidance\n`limit` defaults to 50 and is capped at 200; `offset` defaults to 0 and is capped at 10000. `startDate` and `endDate` must parse as dates. `summaryOnly=true` filters to summary rows where internalId and externalId are null; it does not switch to an aggregate/count-only response shape.\n\n### Request notes\n- `summaryOnly` is a filter for summary sync-log rows, not an aggregation mode.\n- Use entityType/status/direction/date filters to avoid broad exports.\n- The API key selects the organization.\n\n### Response semantics\nHTTP 200 returns `data.logs`, `pagination`, and `meta.organizationId`. Logs include local ids such as id, organizationId, and integrationConfigId, plus status/action metadata. Raw requestPayload, responsePayload, internalId, externalId, endpoint paths, and full error messages are not returned.\n\n### Response notes\n- Rows are sanitized local audit metadata.\n- Local log/config ids may be returned.\n- Raw record identifiers and raw EHR payloads are omitted.\n\n### Errors and retries\nTreat invalid filters as 400, 429 as a backoff signal, and transient 5xx as retryable. Avoid tight polling loops.\n\n### Error notes\n- 400 can indicate invalid enum, date, limit, or offset values.\n- 401/403 require credential, scope, or RBAC correction.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":false,"name":"syncLogId","in":"query","description":"Optional local sync-log id filter scoped to the authenticated organization."},{"schema":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"required":false,"name":"entityType","in":"query","description":"Provider entity classification, such as individual or organization, when the payer workflow requires it."},{"schema":{"type":"string","enum":["SUCCESS","FAILED","CONFLICT","SKIPPED","RETRYING"]},"required":false,"name":"status","in":"query","description":"Sync-log status: SUCCESS, FAILED, CONFLICT, SKIPPED, or RETRYING."},{"schema":{"type":"string","enum":["READ","WRITE"]},"required":false,"name":"direction","in":"query","description":"READ or WRITE log direction."},{"schema":{"type":"string","minLength":1},"required":false,"name":"startDate","in":"query","description":"Start date for a payment plan, service period, or workflow schedule. Use an ISO date string."},{"schema":{"type":"string","minLength":1},"required":false,"name":"endDate","in":"query","description":"ISO datetime upper bound for date-windowed Appeals queries."},{"schema":{"type":"boolean","default":false},"required":false,"name":"summaryOnly","in":"query","description":"When true, filters to sync logs with null internalId and null externalId; it does not return only counts."},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query","description":"Maximum number of records to return. Use bounded pagination and avoid unbounded exports."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query","description":"Zero-based offset for paginated list requests."}],"responses":{"200":{"description":"Sanitized EHR sync logs for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"logs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"integrationConfigId":{"type":"string"},"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"direction":{"type":"string","enum":["READ","WRITE"]},"action":{"type":"string","enum":["CREATE","UPDATE","DELETE","READ","CONFLICT","SKIP"]},"status":{"type":"string","enum":["SUCCESS","FAILED","CONFLICT","SKIPPED","RETRYING"]},"httpMethod":{"type":["string","null"]},"errorCode":{"type":["string","null"]},"durationMs":{"type":["integer","null"]},"retryAttempt":{"type":"integer","minimum":0},"triggeredBy":{"type":"string","enum":["SCHEDULE","EVENT","MANUAL","DEPENDENCY","RETRY"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","integrationConfigId","entityType","direction","action","status","httpMethod","errorCode","durationMs","retryAttempt","triggeredBy","createdAt"]}},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0}},"required":["total","limit","offset"]}},"required":["logs","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"logs":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","integrationConfigId":"00000000-0000-4000-8000-000000000001","entityType":"PATIENT","direction":"READ","action":"CREATE","status":"SUCCESS","httpMethod":"example-httpmethod","errorCode":"example-errorcode","durationMs":1,"retryAttempt":1,"triggeredBy":"SCHEDULE","createdAt":"2026-06-08T10:15:30Z"}],"pagination":{"total":1,"limit":1,"offset":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/config/activate":{"post":{"operationId":"activateEhrIntegrationConfig","summary":"Activate EHR integration configuration","description":"Sets the authenticated organization's local EHR integration configuration to active and returns sanitized config metadata.\n\n### When to use\nUse after reviewing local setup and readiness outside this endpoint.\n\n### Before calling\nConfirm that the organization has an EHR configuration. The endpoint does not perform a live health check.\n\n### Request guidance\nSend an empty JSON body or no fields; organizationId is not a public selector.\n\n### Request notes\n- No organizationId request field.\n- No credentials or vendor payloads are accepted.\n- Use separate health/status processes for live availability.\n\n### Response semantics\nHTTP 200 returns the sanitized config with isActive set by the local update. It is not proof that an external EHR is reachable.\n\n### Response notes\n- Returns sanitized config metadata.\n- Does not return baseUrl or credential values.\n- Does not perform a live health check.\n\n### Errors and retries\nAfter an ambiguous timeout, call getEhrIntegrationConfig before retrying. Back off on 429. A 404 means no organization-scoped EHR integration config exists yet for the API key context; create the config before retrying activation state changes.\n\n### Error notes\n- 403 means the caller lacks write/update permission.\n- 404 means no EHR integration config exists for the authenticated organization.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}},"description":"Send an empty JSON body or no fields; organizationId is not a public selector."},"responses":{"200":{"description":"Sanitized active EHR integration configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"config":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"ehrSystem":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","OTHER"]},"ehrDisplayName":{"type":"string"},"ehrVersion":{"type":["string","null"]},"apiPreference":{"type":"string","enum":["STANDARD_REST","FHIR_R4","HYBRID"]},"isActive":{"type":"boolean"},"healthStatus":{"type":"string","enum":["HEALTHY","DEGRADED","DISCONNECTED","UNKNOWN"]},"lastHealthCheckAt":{"type":["string","null"],"format":"date-time"},"rateLimitPerMinute":{"type":"integer","minimum":0},"retryMaxAttempts":{"type":"integer","minimum":0},"retryBackoffMs":{"type":"integer","minimum":0},"syncBatchSize":{"type":"integer","minimum":1},"enableWebhooks":{"type":"boolean"},"entityConfigs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"syncDirection":{"type":"string","enum":["READ_ONLY","WRITE_ONLY","BIDIRECTIONAL","DISABLED"]},"syncStrategy":{"type":"string","enum":["REAL_TIME","SCHEDULED","ON_DEMAND"]},"syncSchedule":{"type":["string","null"]},"sourceOfTruth":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","RCM_PLATFORM","MANUAL"]},"conflictResolution":{"type":"string","enum":["LAST_WRITE_WINS","SOURCE_OF_TRUTH_WINS","MANUAL_QUEUE"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","entityType","syncDirection","syncStrategy","syncSchedule","sourceOfTruth","conflictResolution","isActive","createdAt","updatedAt"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","ehrSystem","ehrDisplayName","ehrVersion","apiPreference","isActive","healthStatus","lastHealthCheckAt","rateLimitPerMinute","retryMaxAttempts","retryBackoffMs","syncBatchSize","enableWebhooks","entityConfigs","createdAt","updatedAt"]}},"required":["config"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"config":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","ehrSystem":"OPENEMR","ehrDisplayName":"Example activate_ehr_integration_config","ehrVersion":"example-ehrversion","apiPreference":"STANDARD_REST","isActive":true,"healthStatus":"HEALTHY","lastHealthCheckAt":"2026-06-08T10:15:30Z","rateLimitPerMinute":1,"retryMaxAttempts":1,"retryBackoffMs":1,"syncBatchSize":1,"enableWebhooks":true,"entityConfigs":[{"id":"00000000-0000-4000-8000-000000000001","entityType":"PATIENT","syncDirection":"READ_ONLY","syncStrategy":"REAL_TIME","syncSchedule":"example-syncschedule","sourceOfTruth":"OPENEMR","conflictResolution":"LAST_WRITE_WINS","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/config/deactivate":{"post":{"operationId":"deactivateEhrIntegrationConfig","summary":"Deactivate EHR integration configuration","description":"Sets the authenticated organization's local EHR integration configuration to inactive and returns sanitized config metadata.\n\n### When to use\nUse to pause local EHR integration workflows at the configuration level.\n\n### Before calling\nConfirm that deactivation is intended for the organization selected by the API key.\n\n### Request guidance\nSend an empty JSON body or no fields; do not send organizationId, credentials, or vendor payloads.\n\n### Request notes\n- No organizationId request field.\n- No external EHR call is made.\n- No secret material is accepted.\n\n### Response semantics\nHTTP 200 returns the sanitized config with isActive set false by the local update.\n\n### Response notes\n- Returns sanitized config metadata.\n- Does not return baseUrl or credentials.\n- Deactivation is a local config state change.\n\n### Errors and retries\nAfter an ambiguous timeout, call getEhrIntegrationConfig before retrying. Back off on 429. A 404 means no organization-scoped EHR integration config exists yet for the API key context; create the config before retrying activation state changes.\n\n### Error notes\n- 403 means the caller lacks write/update permission.\n- 404 means no EHR integration config exists for the authenticated organization.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}},"description":"Send an empty JSON body or no fields; do not send organizationId, credentials, or vendor payloads."},"responses":{"200":{"description":"Sanitized inactive EHR integration configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"config":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"ehrSystem":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","OTHER"]},"ehrDisplayName":{"type":"string"},"ehrVersion":{"type":["string","null"]},"apiPreference":{"type":"string","enum":["STANDARD_REST","FHIR_R4","HYBRID"]},"isActive":{"type":"boolean"},"healthStatus":{"type":"string","enum":["HEALTHY","DEGRADED","DISCONNECTED","UNKNOWN"]},"lastHealthCheckAt":{"type":["string","null"],"format":"date-time"},"rateLimitPerMinute":{"type":"integer","minimum":0},"retryMaxAttempts":{"type":"integer","minimum":0},"retryBackoffMs":{"type":"integer","minimum":0},"syncBatchSize":{"type":"integer","minimum":1},"enableWebhooks":{"type":"boolean"},"entityConfigs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"syncDirection":{"type":"string","enum":["READ_ONLY","WRITE_ONLY","BIDIRECTIONAL","DISABLED"]},"syncStrategy":{"type":"string","enum":["REAL_TIME","SCHEDULED","ON_DEMAND"]},"syncSchedule":{"type":["string","null"]},"sourceOfTruth":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","RCM_PLATFORM","MANUAL"]},"conflictResolution":{"type":"string","enum":["LAST_WRITE_WINS","SOURCE_OF_TRUTH_WINS","MANUAL_QUEUE"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","entityType","syncDirection","syncStrategy","syncSchedule","sourceOfTruth","conflictResolution","isActive","createdAt","updatedAt"]}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","ehrSystem","ehrDisplayName","ehrVersion","apiPreference","isActive","healthStatus","lastHealthCheckAt","rateLimitPerMinute","retryMaxAttempts","retryBackoffMs","syncBatchSize","enableWebhooks","entityConfigs","createdAt","updatedAt"]}},"required":["config"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"config":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","ehrSystem":"OPENEMR","ehrDisplayName":"Example ehr_integration_config","ehrVersion":"example-ehrversion","apiPreference":"STANDARD_REST","isActive":true,"healthStatus":"HEALTHY","lastHealthCheckAt":"2026-06-08T10:15:30Z","rateLimitPerMinute":1,"retryMaxAttempts":1,"retryBackoffMs":1,"syncBatchSize":1,"enableWebhooks":true,"entityConfigs":[{"id":"00000000-0000-4000-8000-000000000001","entityType":"PATIENT","syncDirection":"READ_ONLY","syncStrategy":"REAL_TIME","syncSchedule":"example-syncschedule","sourceOfTruth":"OPENEMR","conflictResolution":"LAST_WRITE_WINS","isActive":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/config/test":{"post":{"operationId":"testEhrConnection","summary":"Validate EHR connection-test request","description":"Validates a redacted EHR connection-test request shape and credential-status metadata without calling an external EHR adapter.\n\n### When to use\nUse before saving or reviewing config metadata to confirm public request shape and redaction flags.\n\n### Before calling\nPrepare a non-secret baseUrl and redacted credentialStatus flags. This is not a live connectivity test.\n\n### Request guidance\n`baseUrl` is required and must be a URI. `ehrSystem` defaults to OPENEMR and accepts OPENEMR, EPIC, CERNER, ECLINICALWORKS, ATHENA, MEDITECH, or OTHER. `validateOnly` must be true for the public handler; sending false returns 400. `credentialStatus.scopes` accepts up to 50 non-empty strings. `credentialStatus.epicBulkGroupId` may be sent as request metadata, but the response returns only `epicBulkGroupIdConfigured`.\n\n### Request notes\n- `validateOnly` is effectively mandatory as true.\n- Do not include credential values.\n- Use healthStatus/health jobs, not this response, for live availability.\n\n### Response semantics\nHTTP 200 returns `status=VALIDATED`, `validateOnly=true`, `externalRequestMade=false`, and redacted credential-status flags. It does not prove connectivity or expose the Epic group id value.\n\n### Response notes\n- `externalRequestMade` is always false in the documented public response.\n- `epicBulkGroupIdConfigured` is boolean only.\n- No raw endpoint responses or tokens are returned.\n\n### Errors and retries\nCorrect invalid URL, enum, strict-body, or validateOnly=false errors before retrying. Do not poll this as a health check.\n\n### Error notes\n- 400 can mean validateOnly=false or invalid request shape.\n- 403 means write/update permission is missing.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","default":true,"description":"Must be true for the public connection-test handler."},"ehrSystem":{"type":"string","enum":["OPENEMR","EPIC","CERNER","ECLINICALWORKS","ATHENA","MEDITECH","OTHER"],"default":"OPENEMR","description":"Configured vendor enum for request-shape validation. Defaults to OPENEMR."},"baseUrl":{"type":"string","format":"uri","description":"Vendor endpoint base URI accepted for validation; it should not contain embedded credentials and is not returned."},"credentialStatus":{"type":"object","properties":{"hasClientSecret":{"type":"boolean","default":false},"hasPrivateKey":{"type":"boolean","default":false},"hasJwk":{"type":"boolean","default":false},"tokenUrlConfigured":{"type":"boolean","default":false},"scopes":{"type":"array","items":{"type":"string","minLength":1},"maxItems":50,"default":[],"description":"Array of up to 50 non-empty scope strings; do not include tokens or secrets."},"epicBulkGroupId":{"type":"string","minLength":1}},"default":{},"additionalProperties":false,"description":"Redacted credential metadata flags/scopes accepted by the request; never raw credential values."}},"required":["baseUrl"],"additionalProperties":false},"example":{"baseUrl":"https://example.quickintell.com/resource","validateOnly":true,"ehrSystem":"OPENEMR","credentialStatus":{}}}},"description":"`baseUrl` is required and must be a URI. `ehrSystem` defaults to OPENEMR and accepts OPENEMR, EPIC, CERNER, ECLINICALWORKS, ATHENA, MEDITECH, or OTHER. `validateOnly` must be true for the public handler; sending false returns 400. `credentialStatus.scopes` accepts up to 50 non-empty strings. `credentialStatus.epicBulkGroupId` may be sent as request metadata, but the response returns only `epicBulkGroupIdConfigured`."},"responses":{"200":{"description":"Connection-test request validation result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"validateOnly":{"type":"boolean"},"status":{"type":"string","enum":["VALIDATED"]},"externalRequestMade":{"type":"boolean","enum":[false]},"credentialStatus":{"type":"object","properties":{"hasClientSecret":{"type":"boolean"},"hasPrivateKey":{"type":"boolean"},"hasJwk":{"type":"boolean"},"tokenUrlConfigured":{"type":"boolean"},"scopes":{"type":"array","items":{"type":"string"}},"epicBulkGroupIdConfigured":{"type":"boolean"}},"required":["hasClientSecret","hasPrivateKey","hasJwk","tokenUrlConfigured","scopes","epicBulkGroupIdConfigured"]}},"required":["validateOnly","status","externalRequestMade","credentialStatus"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"validateOnly":true,"status":"VALIDATED","externalRequestMade":false,"credentialStatus":{"hasClientSecret":true,"hasPrivateKey":true,"hasJwk":true,"tokenUrlConfigured":true,"scopes":["example-scopes"],"epicBulkGroupIdConfigured":true}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/mappings":{"get":{"operationId":"listEhrMappings","summary":"List EHR mappings","description":"Lists sanitized FIELD or FACILITY mappings for the authenticated organization.\n\n### When to use\nUse this to inspect field transformations or facility mapping state before creating, updating, deleting, or troubleshooting mappings.\n\n### Before calling\nChoose mappingType first. FIELD is the default; FACILITY uses a different filter set and response shape.\n\n### Request guidance\nFor FIELD mappings, `entityConfigId` and `entityType` filter through the parent entity config. `integrationConfigId` and `facilityId` apply to FACILITY mappings only. Transform configuration is not returned.\n\n### Request notes\n- `mappingType` defaults to FIELD.\n- `entityConfigId` and `entityType` are FIELD-oriented filters.\n- `integrationConfigId` and `facilityId` are FACILITY-oriented filters.\n\n### Response semantics\nHTTP 200 returns `data.mappings` as a discriminated union. FIELD rows include entityConfigId/internalField/externalField/direction/transformType/isRequired/defaultValue. FACILITY rows include integrationConfigId/facilityId/externalFacilityId/externalSiteId/isActive.\n\n### Response notes\n- Transform configuration is not returned.\n- No raw vendor payloads or patient values are returned.\n- Local mapping ids are returned for follow-up update/delete calls.\n\n### Errors and retries\nCorrect invalid mappingType/entityType filters before retrying. Back off on 429.\n\n### Error notes\n- 400 can indicate invalid enum/filter values.\n- 403 means read permission is missing.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["FIELD","FACILITY"],"default":"FIELD"},"required":false,"name":"mappingType","in":"query","description":"FIELD or FACILITY. Defaults to FIELD when omitted."},{"schema":{"type":"string","minLength":1},"required":false,"name":"entityConfigId","in":"query","description":"FIELD mapping parent entity-config id filter."},{"schema":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"required":false,"name":"entityType","in":"query","description":"Provider entity classification, such as individual or organization, when the payer workflow requires it."},{"schema":{"type":"string","minLength":1},"required":false,"name":"integrationConfigId","in":"query","description":"FACILITY mapping integration-config id filter."},{"schema":{"type":"string","minLength":1},"required":false,"name":"facilityId","in":"query","description":"FACILITY mapping local facility id filter."}],"responses":{"200":{"description":"Sanitized EHR mappings.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mappings":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"mappingType":{"type":"string","enum":["FIELD"]},"entityConfigId":{"type":"string"},"internalField":{"type":"string"},"externalField":{"type":"string"},"direction":{"type":"string","enum":["READ","WRITE","BIDIRECTIONAL","IGNORED"]},"transformType":{"type":"string","enum":["DIRECT","DATE_FORMAT","CODE_LOOKUP","TEMPLATE","COMPUTED"]},"isRequired":{"type":"boolean"},"defaultValue":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","mappingType","entityConfigId","internalField","externalField","direction","transformType","isRequired","defaultValue","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string"},"mappingType":{"type":"string","enum":["FACILITY"]},"integrationConfigId":{"type":"string"},"facilityId":{"type":"string"},"externalFacilityId":{"type":"string"},"externalSiteId":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","mappingType","integrationConfigId","facilityId","externalFacilityId","externalSiteId","isActive","createdAt","updatedAt"]}]}}},"required":["mappings"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mappings":[{"id":"00000000-0000-4000-8000-000000000001","mappingType":"FIELD","entityConfigId":"00000000-0000-4000-8000-000000000001","internalField":"example-internalfield","externalField":"example-externalfield","direction":"READ","transformType":"DIRECT","isRequired":true,"defaultValue":"example-defaultvalue","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"upsertEhrMapping","summary":"Create or update EHR mapping","description":"Creates or updates a FIELD or FACILITY mapping after verifying parent resources belong to the authenticated organization.\n\n### When to use\nUse FIELD mappings for entity field transforms and FACILITY mappings to associate QuickRCM facilities with external EHR facility/site identifiers.\n\n### Before calling\nDetermine mappingType and create/update mode. For updates, provide the organization-owned mappingId and the required parent id(s) for that mapping type.\n\n### Request guidance\nFIELD creates require `entityConfigId`, `internalField`, and `externalField`. FIELD updates still require `entityConfigId` plus `mappingId`; field names are optional update fields. FACILITY creates require `facilityId` and `externalFacilityId`; FACILITY updates still require `facilityId` plus `mappingId`. `integrationConfigId` is optional for FACILITY mappings but is checked against the current organization config when supplied. Keep `transformConfig` minimal and never include PHI, secrets, raw FHIR resources, or vendor payloads.\n\n### Request notes\n- `mappingType` is required.\n- FIELD and FACILITY have different required fields.\n- The handler verifies organization-scoped parent ownership before mutation.\n\n### Response semantics\nHTTP 200 returns one sanitized mapping. FIELD responses omit transformConfig. FACILITY responses include facility/external facility metadata but not credentials or vendor payloads.\n\n### Response notes\n- Returns one sanitized mapping.\n- `transformConfig` may be accepted but is not returned.\n- No raw vendor payloads or patient values are returned.\n\n### Errors and retries\n400 indicates missing mapping-type-specific requirements or invalid enums. 403 can indicate a supplied integrationConfigId does not match the organization config. 404 can indicate missing entity config, facility, or mapping ownership. After an ambiguous create timeout, list mappings before retrying to avoid duplicates.\n\n### Error notes\n- 400 for missing entityConfigId/internalField/externalField on FIELD create or missing facilityId/externalFacilityId on FACILITY create.\n- 403 when a supplied integrationConfigId is not authorized for the organization.\n- 404 when the parent or mapping is not found in the authenticated organization.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappingType":{"type":"string","enum":["FIELD","FACILITY"],"description":"Mapping discriminator: FIELD or FACILITY."},"mappingId":{"type":"string","minLength":1,"description":"Local mapping id used for mapping update/delete operations."},"entityConfigId":{"type":"string","minLength":1,"description":"Local EHR entity configuration id used as the FIELD mapping parent."},"integrationConfigId":{"type":"string","minLength":1},"internalField":{"type":"string","minLength":1,"maxLength":255,"description":"QuickRCM field path/name for a FIELD mapping; do not use real patient values in examples."},"externalField":{"type":"string","minLength":1,"maxLength":500,"description":"External EHR field path/name for a FIELD mapping; do not embed patient data."},"direction":{"type":"string","enum":["READ","WRITE","BIDIRECTIONAL","IGNORED"],"default":"BIDIRECTIONAL"},"transformType":{"type":"string","enum":["DIRECT","DATE_FORMAT","CODE_LOOKUP","TEMPLATE","COMPUTED"],"default":"DIRECT"},"transformConfig":{"type":"object","additionalProperties":{},"description":"Optional transform settings accepted by the request but omitted from public responses."},"isRequired":{"type":"boolean","default":false},"defaultValue":{"type":["string","null"],"maxLength":500},"facilityId":{"type":"string","minLength":1,"description":"QuickRCM facility identifier scoped to the authenticated organization."},"externalFacilityId":{"type":"string","minLength":1,"maxLength":255,"description":"External EHR facility identifier for a FACILITY mapping."},"externalSiteId":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Optional external EHR site id for multi-site facility mapping."},"isActive":{"type":"boolean","default":true,"description":"FACILITY mapping active flag."}},"required":["mappingType"],"additionalProperties":false},"example":{"mappingType":"FIELD","mappingId":"00000000-0000-4000-8000-000000000001","entityConfigId":"00000000-0000-4000-8000-000000000001","integrationConfigId":"00000000-0000-4000-8000-000000000001","internalField":"example-internalfield","externalField":"example-externalfield","direction":"BIDIRECTIONAL","transformType":"DIRECT","transformConfig":{}}}},"description":"FIELD creates require `entityConfigId`, `internalField`, and `externalField`. FIELD updates still require `entityConfigId` plus `mappingId`; field names are optional update fields. FACILITY creates require `facilityId` and `externalFacilityId`; FACILITY updates still require `facilityId` plus `mappingId`. `integrationConfigId` is optional for FACILITY mappings but is checked against the current organization config when supplied. Keep `transformConfig` minimal and never include PHI, secrets, raw FHIR resources, or vendor payloads."},"responses":{"200":{"description":"Sanitized EHR mapping after create/update.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mapping":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"mappingType":{"type":"string","enum":["FIELD"]},"entityConfigId":{"type":"string"},"internalField":{"type":"string"},"externalField":{"type":"string"},"direction":{"type":"string","enum":["READ","WRITE","BIDIRECTIONAL","IGNORED"]},"transformType":{"type":"string","enum":["DIRECT","DATE_FORMAT","CODE_LOOKUP","TEMPLATE","COMPUTED"]},"isRequired":{"type":"boolean"},"defaultValue":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","mappingType","entityConfigId","internalField","externalField","direction","transformType","isRequired","defaultValue","createdAt","updatedAt"]},{"type":"object","properties":{"id":{"type":"string"},"mappingType":{"type":"string","enum":["FACILITY"]},"integrationConfigId":{"type":"string"},"facilityId":{"type":"string"},"externalFacilityId":{"type":"string"},"externalSiteId":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","mappingType","integrationConfigId","facilityId","externalFacilityId","externalSiteId","isActive","createdAt","updatedAt"]}]}},"required":["mapping"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mapping":{"id":"00000000-0000-4000-8000-000000000001","mappingType":"FIELD","entityConfigId":"00000000-0000-4000-8000-000000000001","internalField":"example-internalfield","externalField":"example-externalfield","direction":"READ","transformType":"DIRECT","isRequired":true,"defaultValue":"example-defaultvalue","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/mappings/{mappingId}":{"delete":{"operationId":"deleteEhrMapping","summary":"Delete EHR mapping","description":"Deletes a FIELD or FACILITY mapping after an organization-scoped ownership lookup.\n\n### When to use\nUse to remove obsolete local field/facility mapping metadata after verifying downstream sync impact.\n\n### Before calling\nLoad mappings with listEhrMappings and confirm whether the target mapping is FIELD or FACILITY.\n\n### Request guidance\n`mappingId` is required in the path and `mappingType` is required in the query. No request body is accepted.\n\n### Request notes\n- `mappingType` is required, not inferred from mappingId.\n- No organizationId selector is accepted.\n- No vendor payloads or credentials are accepted.\n\n### Response semantics\nHTTP 200 returns deleted=true, mappingType, mappingId, and meta.organizationId. It does not return the deleted mapping body.\n\n### Response notes\n- Returns only deletion acknowledgement metadata.\n- No transformConfig or mapping contents are returned.\n- Local mappingId is echoed for reconciliation.\n\n### Errors and retries\nAfter an ambiguous timeout, call listEhrMappings before retrying. Treat 404 as already absent or inaccessible to the tenant, depending on caller context.\n\n### Error notes\n- 400 can indicate missing or invalid mappingType.\n- 404 can indicate the mapping does not exist in the authenticated organization.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"mappingId","in":"path","description":"Local FIELD or FACILITY mapping id to delete."},{"schema":{"type":"string","enum":["FIELD","FACILITY"]},"required":true,"name":"mappingType","in":"query","description":"Required query discriminator: FIELD or FACILITY."}],"responses":{"200":{"description":"Mapping deletion result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"mappingType":{"type":"string","enum":["FIELD","FACILITY"]},"mappingId":{"type":"string"}},"required":["deleted","mappingType","mappingId"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"deleted":true,"mappingType":"FIELD","mappingId":"00000000-0000-4000-8000-000000000001"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/syncs":{"post":{"operationId":"queueEhrManualSync","summary":"Queue EHR manual sync","description":"Queues a local manual EHR sync job for one supported entity type and returns the summary sync-log id.\n\n### When to use\nUse when an admin or automation needs asynchronous local sync work without blocking on external EHR calls.\n\n### Before calling\nConfirm the organization has an EHR integration config. The public handler enforces config existence, queueOnly=true, write permission, and the public entity allowlist; it does not enforce isActive as a public precondition.\n\n### Request guidance\n`entityType` is required but public manual sync accepts only PATIENT, APPOINTMENT, INSURANCE, and ENCOUNTER. `queueOnly` must be true; sending false returns 400. Do not include raw EHR payloads, patient demographics, credentials, or external identifiers.\n\n### Request notes\n- `queueOnly` is effectively mandatory as true.\n- Allowed public entity types are PATIENT, APPOINTMENT, INSURANCE, and ENCOUNTER only.\n- Broader entityType enum values are not supported by this public manual-sync handler.\n\n### Response semantics\nHTTP 202 means QuickRCM accepted local queue work and returned `syncLogId`. It is not a synchronous external EHR success result and not proof that the EHR processed the sync.\n\n### Response notes\n- `syncLogId` is the local audit/reconciliation handle.\n- External EHR execution happens later, if the background job runs successfully.\n\n### Errors and retries\nUse syncLogId and listEhrSyncLogs to reconcile ambiguous retries. Back off on 429 and avoid duplicate queueing after timeouts.\n\n### Error notes\n- 400 for queueOnly=false, missing config, invalid entityType, or entityType outside the public allowlist.\n- 403 means EHR sync-log create permission or write scope is missing.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"],"description":"Manual sync entity type. Public handler allowlist: PATIENT, APPOINTMENT, INSURANCE, ENCOUNTER."},"queueOnly":{"type":"boolean","default":true,"description":"Must be true for public manual sync."}},"required":["entityType"],"additionalProperties":false},"example":{"entityType":"PATIENT","queueOnly":true}}},"description":"`entityType` is required but public manual sync accepts only PATIENT, APPOINTMENT, INSURANCE, and ENCOUNTER. `queueOnly` must be true; sending false returns 400. Do not include raw EHR payloads, patient demographics, credentials, or external identifiers."},"responses":{"202":{"description":"Manual sync queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean","enum":[true]},"queueOnly":{"type":"boolean","enum":[true]},"syncLogId":{"type":"string"},"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]}},"required":["queued","queueOnly","syncLogId","entityType"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"queueOnly":true,"syncLogId":"00000000-0000-4000-8000-000000000001","entityType":"PATIENT"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/syncs/epic-bulk-import":{"post":{"operationId":"queueEpicBulkImport","summary":"Queue Epic bulk import","description":"Queues an Epic Bulk FHIR import job and returns local queue metadata without making an external Epic request in the HTTP handler.\n\n### When to use\nUse for asynchronous Epic bulk-import orchestration after an organization is configured for EPIC.\n\n### Before calling\nConfirm the organization's configured ehrSystem is EPIC and that `groupId` is available from approved operational context. Do not include Epic access tokens, client secrets, private keys, JWKS contents, or raw Bulk FHIR response payloads.\n\n### Request guidance\n`groupId` is required. `queueOnly` must be true; false returns 400. `resourceTypes` is optional, but each value must match `^[A-Za-z][A-Za-z0-9]+$`, with 1-50 values when supplied. If omitted, the handler derives resourceTypes from active entity configs when available, otherwise defaults to Patient, Appointment, Coverage, Encounter, and DocumentReference.\n\n### Request notes\n- `queueOnly` is effectively mandatory as true.\n- Omitted resourceTypes are derived from active entity configs or default to Patient, Appointment, Coverage, Encounter, and DocumentReference.\n\n### Response semantics\nHTTP 202 means local bulk-import work was queued. It is not a completed Epic export/import result and does not prove Epic accepted a request. The response returns the normalized resourceTypes selected for the queued job.\n\n### Response notes\n- `resourceTypes` in the response is the normalized list used for the queued job.\n- The handler does not select stored credentials or call Epic synchronously.\n\n### Errors and retries\nUse retryOfSyncLogId for controlled retries when available. After ambiguous failures, inspect sync logs before queueing duplicate bulk imports.\n\n### Error notes\n- 400 for queueOnly=false, missing config, non-EPIC config, missing groupId, or invalid resourceTypes.\n- 403 means EHR sync-log create permission or write scope is missing.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"groupId":{"type":"string","minLength":1,"maxLength":255,"description":"Epic bulk group identifier. Use synthetic values in examples and avoid secrets."},"resourceTypes":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]+$"},"minItems":1,"maxItems":50,"description":"FHIR resource type names for the import workflow; values must be alphanumeric and start with a letter."},"retryOfSyncLogId":{"type":"string","minLength":1,"description":"Optional prior local sync-log id this request is retrying."},"queueOnly":{"type":"boolean","default":true,"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."}},"required":["groupId"],"additionalProperties":false},"example":{"groupId":"00000000-0000-4000-8000-000000000001","resourceTypes":["example-resourcetypes"],"retryOfSyncLogId":"00000000-0000-4000-8000-000000000001","queueOnly":true}}},"description":"`groupId` is required. `queueOnly` must be true; false returns 400. `resourceTypes` is optional, but each value must match `^[A-Za-z][A-Za-z0-9]+$`, with 1-50 values when supplied. If omitted, the handler derives resourceTypes from active entity configs when available, otherwise defaults to Patient, Appointment, Coverage, Encounter, and DocumentReference."},"responses":{"202":{"description":"Epic bulk import queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean","enum":[true]},"queueOnly":{"type":"boolean","enum":[true]},"syncLogId":{"type":"string"},"resourceTypes":{"type":"array","items":{"type":"string"}}},"required":["queued","queueOnly","syncLogId","resourceTypes"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"queueOnly":true,"syncLogId":"00000000-0000-4000-8000-000000000001","resourceTypes":["example-resourcetypes"]},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/syncs/record/validate":{"post":{"operationId":"validateEhrRecordSync","summary":"Validate EHR record sync","description":"Dry-run validates a single EHR record-sync request and reports whether a matching local EHR id mapping exists.\n\n### When to use\nUse before enabling record-level automation to check request shape, configured EHR context, and local mapping presence without queueing work.\n\n### Before calling\nResolve the intended local internalId from approved application context. This endpoint does not verify that the source record itself exists; it checks the organization-scoped EhrIdMapping for internalId/entityType/externalSystem.\n\n### Request guidance\n`entityType`, `internalId`, and `direction` are required. `direction` is READ or WRITE. `dryRun` must be true; false returns 400. Do not include external payloads, raw FHIR resources, patient demographics, credentials, or tokens.\n\n### Request notes\n- `dryRun` is effectively mandatory as true.\n- `internalId` is checked against EhrIdMapping, not against the source table.\n- The configured ehrSystem determines externalSystem for the mapping lookup.\n\n### Response semantics\nHTTP 200 returns `dryRun=true`, `status=VALIDATED`, `externalRequestMade=false`, and `mappingExists`. `mappingExists` is based on EhrIdMapping rows scoped by organizationId, entityType, internalId, and externalSystem derived from the configured ehrSystem.\n\n### Response notes\n- `externalRequestMade` is false.\n- `mappingExists=false` can be a valid validation result.\n- No raw internal/external ids beyond the submitted internalId are returned.\n\n### Errors and retries\nCorrect invalid entityType, direction, missing config, or dryRun=false before retrying. Do not document 403/404 as proof that the internal source record is inaccessible; this handler does not check source-record existence.\n\n### Error notes\n- 400 for dryRun=false or invalid request shape.\n- 400 if no EHR integration is configured for the organization.\n- 403 means write/create permission is missing.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"],"description":"Provider entity classification, such as individual or organization, when the payer workflow requires it."},"internalId":{"type":"string","minLength":1,"description":"Local QuickRCM record id supplied by the caller for mapping validation; the handler checks EhrIdMapping, not the source record table."},"direction":{"type":"string","enum":["READ","WRITE"],"description":"Requested validation direction: READ or WRITE."},"dryRun":{"type":"boolean","default":true,"description":"Simulates the action without creating a task or making an external submission. Use this to verify request shape safely."}},"required":["entityType","internalId","direction"],"additionalProperties":false},"example":{"entityType":"PATIENT","internalId":"00000000-0000-4000-8000-000000000001","direction":"READ","dryRun":true}}},"description":"`entityType`, `internalId`, and `direction` are required. `direction` is READ or WRITE. `dryRun` must be true; false returns 400. Do not include external payloads, raw FHIR resources, patient demographics, credentials, or tokens."},"responses":{"200":{"description":"Record sync dry-run validation result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"dryRun":{"type":"boolean","enum":[true]},"status":{"type":"string","enum":["VALIDATED"]},"externalRequestMade":{"type":"boolean","enum":[false]},"mappingExists":{"type":"boolean"}},"required":["dryRun","status","externalRequestMade","mappingExists"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"dryRun":true,"status":"VALIDATED","externalRequestMade":false,"mappingExists":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/syncs/full-resync/validate":{"post":{"operationId":"validateEhrFullResync","summary":"Validate EHR full resync","description":"Dry-run validates a full-resync request and counts organization-scoped EHR id mappings that would be affected for the configured external system and entity type.\n\n### When to use\nUse before a planned full resync to preview local id-mapping impact safely.\n\n### Before calling\nConfirm the entity type and configured EHR system. This endpoint reports mapping impact only; it does not execute a resync.\n\n### Request guidance\n`entityType` is required. `dryRun` must be true; false returns 400. Do not include vendor payloads, patient data, credentials, or tokens.\n\n### Request notes\n- `dryRun` is effectively mandatory as true.\n- `wouldDeleteMappings` refers to EhrIdMapping rows only.\n- externalSystem is derived from the configured ehrSystem.\n\n### Response semantics\nHTTP 200 returns `dryRun=true`, `status=VALIDATED`, `externalRequestMade=false`, and `wouldDeleteMappings`. `wouldDeleteMappings` counts EhrIdMapping rows scoped by organizationId, entityType, and externalSystem derived from the configured ehrSystem. It does not count or delete field mappings or facility mappings.\n\n### Response notes\n- `externalRequestMade` is false.\n- No mappings are deleted by this endpoint.\n- The response is not a live EHR status check.\n\n### Errors and retries\nCorrect invalid entity type, missing config, or dryRun=false before retrying. Do not use this as proof of live EHR availability.\n\n### Error notes\n- 400 for dryRun=false or invalid request shape.\n- 400 if no EHR integration is configured.\n- 403 means write/create permission is missing.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"],"description":"Provider entity classification, such as individual or organization, when the payer workflow requires it."},"dryRun":{"type":"boolean","default":true,"description":"Must be true for this public validation route."}},"required":["entityType"],"additionalProperties":false},"example":{"entityType":"PATIENT","dryRun":true}}},"description":"`entityType` is required. `dryRun` must be true; false returns 400. Do not include vendor payloads, patient data, credentials, or tokens."},"responses":{"200":{"description":"Full resync dry-run validation result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"dryRun":{"type":"boolean","enum":[true]},"status":{"type":"string","enum":["VALIDATED"]},"externalRequestMade":{"type":"boolean","enum":[false]},"wouldDeleteMappings":{"type":"integer","minimum":0}},"required":["dryRun","status","externalRequestMade","wouldDeleteMappings"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"dryRun":true,"status":"VALIDATED","externalRequestMade":false,"wouldDeleteMappings":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/conflicts":{"get":{"operationId":"listEhrSyncConflicts","summary":"List EHR sync conflicts","description":"Lists sanitized EHR sync conflicts for the authenticated organization with entityType, resolution, and pagination filters.\n\n### When to use\nUse to populate conflict queues, review pending or resolved conflict metadata, or find a conflict id before resolving it.\n\n### Before calling\nChoose filters and pagination. Default resolution is PENDING.\n\n### Request guidance\n`limit` defaults to 50 and is capped at 200; `offset` defaults to 0 and is capped at 10000. `resolution` can be KEEP_LOCAL, KEEP_REMOTE, MERGE, or PENDING.\n\n### Request notes\n- `resolution` defaults to PENDING.\n- Use entityType to narrow conflict queues.\n- No organizationId selector is accepted.\n\n### Response semantics\nHTTP 200 returns `data.conflicts`, pagination, and meta.organizationId. Conflict rows include local ids, organizationId, entityType, conflictFields, resolution, resolvedBy, resolvedAt, and createdAt. Raw localData, remoteData, internalId, externalId, and full record payloads are not returned.\n\n### Response notes\n- `conflictFields` contains field names only.\n- Local conflict ids and organizationId may be returned.\n- Raw local/remote conflict payloads and internal/external record ids are omitted.\n\n### Errors and retries\nCorrect invalid filters before retrying. Back off on 429.\n\n### Error notes\n- 400 for invalid enum or pagination values.\n- 403 means read permission is missing.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"required":false,"name":"entityType","in":"query","description":"Provider entity classification, such as individual or organization, when the payer workflow requires it."},{"schema":{"type":"string","enum":["KEEP_LOCAL","KEEP_REMOTE","MERGE","PENDING"],"default":"PENDING"},"required":false,"name":"resolution","in":"query","description":"Conflict resolution state: PENDING, KEEP_LOCAL, KEEP_REMOTE, or MERGE."},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query","description":"Maximum number of records to return. Use bounded pagination and avoid unbounded exports."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"offset","in":"query","description":"Zero-based offset for paginated list requests."}],"responses":{"200":{"description":"Sanitized EHR sync conflicts for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conflicts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"conflictFields":{"type":"array","items":{"type":"string"}},"resolution":{"type":"string","enum":["KEEP_LOCAL","KEEP_REMOTE","MERGE","PENDING"]},"resolvedBy":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","entityType","conflictFields","resolution","resolvedBy","resolvedAt","createdAt"]}},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0}},"required":["total","limit","offset"]}},"required":["conflicts","pagination"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"conflicts":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","entityType":"PATIENT","conflictFields":["example-conflictfields"],"resolution":"KEEP_LOCAL","resolvedBy":"example-resolvedby","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z"}],"pagination":{"total":1,"limit":1,"offset":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/ehr-integration/conflicts/{conflictId}/resolve":{"put":{"operationId":"resolveEhrSyncConflict","summary":"Resolve EHR sync conflict","description":"Records a local resolution state for a pending EHR sync conflict and returns sanitized conflict metadata.\n\n### When to use\nUse after an authorized review workflow chooses KEEP_LOCAL, KEEP_REMOTE, or MERGE for a pending conflict.\n\n### Before calling\nLoad pending conflict metadata with listEhrSyncConflicts. The handler requires the conflict to belong to the authenticated organization and still be PENDING.\n\n### Request guidance\n`conflictId` is required in the path and `resolution` is required in the body. `mergeData` is accepted by the schema, but the current public handler records only resolution, resolvedBy, and resolvedAt; it does not apply mergeData values or return merged field values. Do not send raw local/remote payloads, full FHIR resources, credentials, or unnecessary PHI.\n\n### Request notes\n- `resolution` may be KEEP_LOCAL, KEEP_REMOTE, or MERGE.\n- The conflict must currently be PENDING.\n- `mergeData` is not reflected in the public response and should not be described as applied field updates.\n\n### Response semantics\nHTTP 200 returns sanitized conflict metadata after the local resolution update. Raw local and remote conflict payloads are never returned. MERGE should be documented as a recorded resolution choice unless a future handler applies mergeData.\n\n### Response notes\n- Returns sanitized conflict metadata.\n- Raw localData and remoteData are omitted.\n- `resolvedBy` and `resolvedAt` are set by the local update.\n\n### Errors and retries\n400 can indicate invalid resolution or that the conflict is already resolved. 404 can indicate no pending organization-scoped conflict with that id. After ambiguous timeouts, re-list conflicts before retrying.\n\n### Error notes\n- 400 if the conflict is already resolved.\n- 404 if conflictId is not found for the authenticated organization.\n","tags":["EHR Integration"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"conflictId","in":"path","description":"Local conflict id in the path; must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string","enum":["KEEP_LOCAL","KEEP_REMOTE","MERGE"],"description":"Requested local resolution state: KEEP_LOCAL, KEEP_REMOTE, or MERGE."},"mergeData":{"type":"object","additionalProperties":{},"description":"Optional schema field; current public handler does not apply or return merged field values."}},"required":["resolution"],"additionalProperties":false},"example":{"resolution":"KEEP_LOCAL","mergeData":{}}}},"description":"`conflictId` is required in the path and `resolution` is required in the body. `mergeData` is accepted by the schema, but the current public handler records only resolution, resolvedBy, and resolvedAt; it does not apply mergeData values or return merged field values. Do not send raw local/remote payloads, full FHIR resources, credentials, or unnecessary PHI."},"responses":{"200":{"description":"Sanitized resolved conflict.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conflict":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"entityType":{"type":"string","enum":["PATIENT","APPOINTMENT","ENCOUNTER","INSURANCE","INSURANCE_COMPANY","ALLERGY","MEDICATION","MEDICAL_PROBLEM","VITAL","SOAP_NOTE","PROCEDURE","DOCUMENT","PRACTITIONER","FACILITY","CLAIM_STATUS","PAYMENT","DENIAL","PRIOR_AUTH","CODING"]},"conflictFields":{"type":"array","items":{"type":"string"}},"resolution":{"type":"string","enum":["KEEP_LOCAL","KEEP_REMOTE","MERGE","PENDING"]},"resolvedBy":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","entityType","conflictFields","resolution","resolvedBy","resolvedAt","createdAt"]}},"required":["conflict"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"conflict":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","entityType":"PATIENT","conflictFields":["example-conflictfields"],"resolution":"KEEP_LOCAL","resolvedBy":"example-resolvedby","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization or resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/eligibility/checks":{"post":{"operationId":"createEligibilityCheck","summary":"Create eligibility check","description":"Creates an eligibility verification workflow for the authenticated organization and returns a sanitized eligibilityCheck summary.\n\n### When to use\nUse this for on-demand eligibility initiation when an integration has patient identity fields plus payer context. The runtime contract requires either payerId or insurance_provider in addition to patientFirstName, patientLastName, and patientDOB.\n\n### Before calling\nAuthenticate with a tenant-scoped bearer API key with eligibility write access. Resolve payerId when possible, or provide insurance_provider when the caller only has a payer display name. If providerId or batchId is supplied, make sure it belongs to the same authenticated organization before sending the request.\n\n### Request guidance\nSend JSON-native fields only. Do not send raw X12 270/271 eligibility EDI, payer portal credentials, tokens, raw payer payloads, transcripts, or broad clinical notes in contextData. Treat patient names, dates of birth, member identifiers, subscriber identifiers, and payer identifiers as Protected Health Information (PHI) or PHI-adjacent data.\n\n### Request notes\n- OpenAPI marks patientFirstName, patientLastName, and patientDOB as required; the runtime Zod refinement also requires either payerId or insurance_provider.\n- Request serviceType is an array of up to 20 strings. Response eligibilityCheck.serviceType is a single string or null.\n- procedureCodes accepts up to 50 strings of up to 40 characters each.\n- providerId is checked against active providers in the authenticated organization before the check runs.\n- batchId is checked against the authenticated organization before the check is associated with a batch.\n\n### Response semantics\nA 201 response returns success, data.eligibilityCheck, and meta.organizationId. The eligibilityCheck object contains IDs such as patientId and patientInsuranceId, nullable appointmentId and batchId, status, statusCode, processingMode, a nullable payer summary, result, dateOfService, and createdAt. It does not return patient demographics, full insurance detail objects, requestPayload, responsePayload, benefitsData, raw payer details, or proof that coverage will pay a claim.\n\n### Response notes\n- The response is a local QuickRCM summary for the authenticated organization.\n- payer is a nullable normalized object with payerId and payerName, not a raw payer response.\n- result repeats normalized status and statusCode values for integrations that consume a compact result object.\n- appointmentId and batchId can be null because eligibility checks may be standalone.\n\n### Errors and retries\nFix 400 validation errors before retrying; the payer one-of rule can produce a 400 when neither payerId nor insurance_provider is present. Correct 401 credential failures, 403 authorization or scope failures, and tenant-access issues before retrying. Back off on 429. Retry transient 5xx responses only with caller-side duplicate-request controls.\n\n### Error notes\n- 400 means the body failed schema validation or the payer one-of rule.\n- 403 indicates the authenticated API key lacks required access, scope, or organization authorization for this workflow.\n- 429 requires rate-limit backoff rather than immediate polling.\n","tags":["Eligibility"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientFirstName":{"type":"string","minLength":1,"maxLength":100,"description":"Patient first name for request matching. It is required in the request and omitted from the public response."},"patientLastName":{"type":"string","minLength":1,"maxLength":100,"description":"Patient last name for prior authorization create or draft flows. Use synthetic values in public examples."},"patientDOB":{"type":"string","minLength":1,"description":"Patient date of birth as YYYY-MM-DD or another accepted ISO-style date string. Treat as Protected Health Information (PHI)."},"memberId":{"type":"string","minLength":1,"maxLength":120,"description":"Subscriber or member identifier from the insurance coverage context. Treat as Protected Health Information (PHI)."},"payerId":{"type":"string","minLength":1,"maxLength":120,"description":"Payer identifier used by QuickRCM eligibility workflows. Runtime validation requires payerId when insurance_provider is absent."},"insurance_provider":{"type":"string","minLength":1,"maxLength":200,"description":"Payer display name supplied when the caller does not have payerId. Runtime validation requires insurance_provider when payerId is absent."},"procedureCodes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":50,"description":"Procedure or service codes used as request context. The OpenAPI schema allows up to 50 strings."},"placeOfService":{"type":"string","minLength":1,"maxLength":20,"description":"Service location code used as eligibility context, such as a Centers for Medicare & Medicaid Services (CMS) place-of-service code."},"serviceType":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"maxItems":20,"description":"Request field is an array of service type code strings; response field is a single service type string or null."},"providerNpi":{"type":"string","minLength":1,"maxLength":20,"description":"National Provider Identifier (NPI) for the rendering, billing, or service provider context."},"providerType":{"type":"string","minLength":1,"maxLength":20,"description":"Availity provider type code, for example AT for Professional or H for Institutional."},"providerId":{"type":"string","minLength":1,"description":"QuickRCM provider identifier. The handler verifies active provider ownership in the authenticated organization."},"appointmentDate":{"type":"string","minLength":1,"description":"Requested eligibility date of service. Use an ISO-style date string and do not use it as a broad search field."},"batchId":{"type":"string","minLength":1,"description":"Optional QuickRCM bulk eligibility batch identifier. The handler verifies it belongs to the authenticated organization before associating it with the check."},"doctor":{"type":"string","minLength":1,"maxLength":200,"description":"Optional provider display name stored as request context, not a substitute for providerNpi or providerId."},"location":{"type":"string","minLength":1,"maxLength":200},"relationship":{"type":"string","minLength":1,"maxLength":50,"description":"Subscriber-to-patient relationship value for the coverage context."},"subscriberFirstName":{"type":"string","minLength":1,"maxLength":100,"description":"Subscriber first name for dependent or non-self coverage checks. Treat as Protected Health Information (PHI)."},"subscriberLastName":{"type":"string","minLength":1,"maxLength":100,"description":"Subscriber last name for dependent or non-self coverage checks. Treat as Protected Health Information (PHI)."},"subscriberDOB":{"type":"string","minLength":1,"description":"Subscriber date of birth when the subscriber differs from the patient. Treat as Protected Health Information (PHI)."},"contextData":{"type":"object","additionalProperties":{},"description":"Caller-supplied workflow metadata. Keep it minimal and exclude credentials, tokens, raw payer payloads, raw EDI, transcripts, and unnecessary Protected Health Information (PHI)."},"forceRecheck":{"type":"boolean","description":"Boolean request flag asking for a fresh check where supported. Do not describe it as a guaranteed payer requery without stronger public evidence."},"checkSecondary":{"type":"boolean","description":"Boolean request flag for secondary-coverage handling. It is a request hint, not proof that a secondary payer response will be returned."}},"required":["patientFirstName","patientLastName","patientDOB"]},"example":{"patientFirstName":"Example eligibility_check","patientLastName":"Example eligibility_check","patientDOB":"1984-03-22","memberId":"W123456789","payerId":"87726","insurance_provider":"example-insurance_provider","procedureCodes":["example-procedurecodes"],"placeOfService":"example-placeofservice","serviceType":["30"],"providerNpi":"1234567893","providerType":"example-providertype"}}},"description":"Send JSON-native fields only. Do not send raw X12 270/271 eligibility EDI, payer portal credentials, tokens, raw payer payloads, transcripts, or broad clinical notes in contextData. Treat patient names, dates of birth, member identifiers, subscriber identifiers, and payer identifiers as Protected Health Information (PHI) or PHI-adjacent data."},"responses":{"201":{"description":"Created eligibility check summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"eligibilityCheck":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"patientInsuranceId":{"type":"string"},"batchId":{"type":["string","null"]},"serviceType":{"type":["string","null"]},"dateOfService":{"type":"string","format":"date-time"},"status":{"type":"string"},"statusCode":{"type":["string","null"]},"processingMode":{"type":["string","null"]},"payer":{"type":["object","null"],"properties":{"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["payerId","payerName"]},"result":{"type":"object","properties":{"status":{"type":"string"},"statusCode":{"type":["string","null"]}},"required":["status","statusCode"]},"details":{"type":"object","properties":{"responsePayload":{"description":"Stored Availity-shaped eligibility response returned by the automated vendor, when available. Stedi responses are normalized into this shape and include sourceVendor: \"Stedi\"."},"benefitsData":{"description":"The first Availity-shaped eligibility plan stored for this check, when available. For Stedi-routed checks this comes from the normalized Stedi response."}}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","appointmentId","patientInsuranceId","batchId","serviceType","dateOfService","status","statusCode","processingMode","payer","result","details","createdAt"]}},"required":["eligibilityCheck"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"eligibilityCheck":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","batchId":"00000000-0000-4000-8000-000000000001","serviceType":"30","dateOfService":"2026-06-08T10:15:30Z","status":"active","statusCode":"example-statuscode","processingMode":"example-processingmode","payer":{"payerId":"87726","payerName":"Example eligibility_check"},"result":{"status":"active","statusCode":"example-statuscode"},"details":{"responsePayload":"example-responsepayload","benefitsData":"example-benefitsdata"},"createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/eligibility/checks/{eligibilityCheckId}":{"get":{"operationId":"getEligibilityCheck","summary":"Get eligibility check","description":"Returns one sanitized eligibilityCheck summary when eligibilityCheckId belongs to the authenticated organization.\n\n### When to use\nUse this after createEligibilityCheck, a batch workflow, or another QuickRCM workflow gives you an eligibilityCheckId and you need current local status.\n\n### Before calling\nUse an eligibilityCheckId obtained from a trusted QuickRCM response in the same tenant context as the bearer API key.\n\n### Request guidance\nPass only the path identifier. Do not send organizationId selectors, payer credentials, raw EDI, raw payer payloads, or patient search data.\n\n### Request notes\n- Use the path eligibilityCheckId from a prior QuickRCM response.\n- The bearer API key selects the tenant; do not send tenant selectors in the body or query.\n\n### Response semantics\nA 200 response returns success, data.eligibilityCheck, and meta.organizationId with the same sanitized response shape as createEligibilityCheck. It returns IDs and normalized status fields, not patient demographics or full benefit detail.\n\n### Response notes\n- The result is a local summary and may contain null appointmentId, batchId, payer, statusCode, or processingMode.\n- The response does not include raw X12 271 Health Care Eligibility Benefit Response data, raw payer payloads, requestPayload, responsePayload, benefitsData, or patient demographics.\n\n### Errors and retries\nTreat 404 as missing or unavailable to this organization unless a recent same-tenant create response proves otherwise. Treat 403 as an authorization, scope, or authenticated-organization access failure rather than the normal wrong-ID outcome for a resource lookup. Retry 429 and transient 5xx with backoff. Do not retry 401 or 403 until credentials or scopes change.\n\n### Error notes\n- 404 can mean the record does not exist or is outside the authenticated organization.\n- 403 indicates the authenticated API key lacks required access, scope, or organization authorization; wrong-tenant resource IDs should be documented as 404 when the endpoint hides resource existence.\n- 429 requires backoff before polling again.\n","tags":["Eligibility"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"eligibilityCheckId","in":"path","description":"QuickRCM eligibility check identifier from a tenant-scoped create, batch, or workflow response."}],"responses":{"200":{"description":"Eligibility check summary for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"eligibilityCheck":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"patientInsuranceId":{"type":"string"},"batchId":{"type":["string","null"]},"serviceType":{"type":["string","null"]},"dateOfService":{"type":"string","format":"date-time"},"status":{"type":"string"},"statusCode":{"type":["string","null"]},"processingMode":{"type":["string","null"]},"payer":{"type":["object","null"],"properties":{"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]}},"required":["payerId","payerName"]},"result":{"type":"object","properties":{"status":{"type":"string"},"statusCode":{"type":["string","null"]}},"required":["status","statusCode"]},"details":{"type":"object","properties":{"responsePayload":{"description":"Stored Availity-shaped eligibility response returned by the automated vendor, when available. Stedi responses are normalized into this shape and include sourceVendor: \"Stedi\"."},"benefitsData":{"description":"The first Availity-shaped eligibility plan stored for this check, when available. For Stedi-routed checks this comes from the normalized Stedi response."}}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","appointmentId","patientInsuranceId","batchId","serviceType","dateOfService","status","statusCode","processingMode","payer","result","details","createdAt"]}},"required":["eligibilityCheck"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"eligibilityCheck":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","batchId":"00000000-0000-4000-8000-000000000001","serviceType":"30","dateOfService":"2026-06-08T10:15:30Z","status":"active","statusCode":"example-statuscode","processingMode":"example-processingmode","payer":{"payerId":"87726","payerName":"Example eligibility_check"},"result":{"status":"active","statusCode":"example-statuscode"},"details":{"responsePayload":"example-responsepayload","benefitsData":"example-benefitsdata"},"createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Eligibility check not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/eligibility/batches":{"post":{"operationId":"createEligibilityBatch","summary":"Create bulk eligibility batch","description":"Validates and creates a safe organization-scoped bulk eligibility batch wrapper for CSV-backed or Amazon S3-backed batch input.\n\n### When to use\nUse this when an integration needs to validate CSV content, register an already uploaded object by synthetic object-key placeholder, create a local batch wrapper, or prepare local queued state for later processing.\n\n### Before calling\nAuthenticate with an eligibility write-scoped API key. Prepare fileName plus either csvContent or both s3Key and totalRows. Use validateOnly or dryRun before production queueing, and use idempotencyKey only for retries of the exact same file or object metadata.\n\n### Request guidance\nfileName is required. csvContent must contain only the minimum data needed for eligibility validation and should not be logged. s3Key is placeholder object metadata in public examples, not credentials, signed URLs, real storage paths, or object contents. totalRows is required when using s3Key without csvContent.\n\n### Request notes\n- Runtime validation requires csvContent or the pair s3Key plus totalRows.\n- fileName has a 255-character maximum, fileType has a 120-character maximum, s3Key has a 1024-character maximum, idempotencyKey has a 200-character maximum, and totalRows is a positive integer capped at 100000.\n- For csvContent, implementation tests use firstName,lastName,DOB,memberID,appointmentDate plus payerID or insuranceCompany headers. Confirm with product before publishing a full CSV template as a contractual guarantee.\n- validateOnly and dryRun both return validation-style 200 responses without creating a batch.\n\n### Response semantics\nA 200 response can represent validation-only, dry-run, or idempotent replay behavior. A 201 response creates a local batch wrapper. The response envelope contains success, data.batch, data.validation, data.queue, and meta.organizationId. data.batch is null for validation-only responses and present for created or replayed batches. The response does not echo raw CSV rows or object contents.\n\n### Response notes\n- validation.valid summarizes whether validation passed.\n- validation.errors is row-level validation metadata and is not a raw CSV echo.\n- queue.mode is local workflow metadata, not payer status.\n- batch.checkSummary is an aggregate and does not expose row-level PHI.\n\n### Errors and retries\nCorrect malformed file metadata, missing csvContent/s3Key+totalRows, invalid CSV rows, or bound violations before retrying 400 responses. Retry with the same idempotencyKey only for the same payload. Correct 401 credential failures and 403 authorization or scope failures before retrying. Back off on 429 and retry only transient 5xx responses.\n\n### Error notes\n- 400 indicates invalid request shape, file metadata, missing source fields, or validation input.\n- 401 and 403 require credential, scope, or organization-access correction before retrying.\n- 429 should be retried only after rate-limit backoff.\n","tags":["Eligibility"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Display name for the eligibility batch file, up to 255 characters. Avoid embedding patient identifiers in the file name."},"fileType":{"type":"string","minLength":1,"maxLength":120,"description":"MIME type or file classification for the eligibility batch source file, up to 120 characters."},"csvContent":{"type":"string","minLength":1,"description":"Comma-separated values (CSV) content for validation or local queue creation. Raw CSV is not returned by the public API and should not contain unnecessary Protected Health Information (PHI)."},"s3Key":{"type":"string","minLength":1,"maxLength":1024,"description":"Amazon Simple Storage Service (Amazon S3) object key metadata, up to 1024 characters. Do not publish real object keys, signed URLs, credentials, or object contents in docs examples."},"totalRows":{"type":"integer","exclusiveMinimum":0,"maximum":100000,"description":"Positive integer row count for the batch source file. Required when using s3Key without csvContent and capped at 100000."},"validateOnly":{"type":"boolean","description":"Validates the batch payload and returns validation information without creating the full batch workflow."},"dryRun":{"type":"boolean","description":"Runs validation-style behavior without creating or queueing the batch. The current handler treats dryRun like validateOnly for createEligibilityBatch."},"queueOnly":{"type":"boolean","description":"Requests local queue-ready behavior rather than inline external processing."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-provided retry key, up to 200 characters, for replay protection on the exact same batch creation request."}},"required":["fileName"]},"example":{"fileName":"Example eligibility_batch","fileType":"example-filetype","csvContent":"example-csvcontent","s3Key":"example-s3key","totalRows":1,"validateOnly":true,"dryRun":true,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"fileName is required. csvContent must contain only the minimum data needed for eligibility validation and should not be logged. s3Key is placeholder object metadata in public examples, not credentials, signed URLs, real storage paths, or object contents. totalRows is required when using s3Key without csvContent."},"responses":{"200":{"description":"Batch validation result or idempotent existing batch.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"batch":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"fileName":{"type":"string"},"status":{"type":"string"},"totalRows":{"type":"integer"},"processedRows":{"type":"integer"},"failedRows":{"type":"integer"},"progressPercentage":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkSummary":{"type":"object","properties":{"total":{"type":"integer"},"eligible":{"type":"integer"},"ineligible":{"type":"integer"},"pending":{"type":"integer"},"failed":{"type":"integer"}},"required":["total","eligible","ineligible","pending","failed"]}},"required":["id","organizationId","fileName","status","totalRows","processedRows","failedRows","progressPercentage","startedAt","completedAt","createdAt","updatedAt","checkSummary"]},"validation":{"type":"object","properties":{"valid":{"type":"boolean"},"totalRows":{"type":"integer"},"fileHash":{"type":["string","null"]},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"message":{"type":"string"}},"required":["row","message"]}}},"required":["valid","totalRows","fileHash","errors"]},"queue":{"type":"object","properties":{"queued":{"type":"boolean"},"mode":{"type":"string"}},"required":["queued","mode"]}},"required":["batch","validation","queue"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"batch":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","fileName":"Example eligibility_batch","status":"active","totalRows":1,"processedRows":1,"failedRows":1,"progressPercentage":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","checkSummary":{"total":1,"eligible":1,"ineligible":1,"pending":1,"failed":1}},"validation":{"valid":true,"totalRows":1,"fileHash":"example-filehash","errors":[{"row":1,"message":"Request failed"}]},"queue":{"queued":true,"mode":"example-mode"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"201":{"description":"Created bulk eligibility batch.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"batch":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"fileName":{"type":"string"},"status":{"type":"string"},"totalRows":{"type":"integer"},"processedRows":{"type":"integer"},"failedRows":{"type":"integer"},"progressPercentage":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkSummary":{"type":"object","properties":{"total":{"type":"integer"},"eligible":{"type":"integer"},"ineligible":{"type":"integer"},"pending":{"type":"integer"},"failed":{"type":"integer"}},"required":["total","eligible","ineligible","pending","failed"]}},"required":["id","organizationId","fileName","status","totalRows","processedRows","failedRows","progressPercentage","startedAt","completedAt","createdAt","updatedAt","checkSummary"]},"validation":{"type":"object","properties":{"valid":{"type":"boolean"},"totalRows":{"type":"integer"},"fileHash":{"type":["string","null"]},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"message":{"type":"string"}},"required":["row","message"]}}},"required":["valid","totalRows","fileHash","errors"]},"queue":{"type":"object","properties":{"queued":{"type":"boolean"},"mode":{"type":"string"}},"required":["queued","mode"]}},"required":["batch","validation","queue"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"batch":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","fileName":"Example eligibility_batch","status":"active","totalRows":1,"processedRows":1,"failedRows":1,"progressPercentage":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","checkSummary":{"total":1,"eligible":1,"ineligible":1,"pending":1,"failed":1}},"validation":{"valid":true,"totalRows":1,"fileHash":"example-filehash","errors":[{"row":1,"message":"Request failed"}]},"queue":{"queued":true,"mode":"example-mode"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/eligibility/batches/{batchId}":{"get":{"operationId":"getEligibilityBatch","summary":"Get bulk eligibility batch","description":"Returns sanitized bulk eligibility batch progress and aggregate check status for a batch owned by the authenticated organization.\n\n### When to use\nUse this to poll or display batch progress after createEligibilityBatch or queueEligibilityBatch returns a batchId.\n\n### Before calling\nUse a batchId from the same tenant context and choose a polling interval that respects API key rate limits.\n\n### Request guidance\nPass only the path batchId. Do not send raw CSV, Amazon S3 credentials, signed URLs, object contents, payer credentials, or organization selectors.\n\n### Request notes\n- Use batchId from createEligibilityBatch or queueEligibilityBatch.\n- Avoid tight polling loops; batch progress is local workflow state.\n\n### Response semantics\nA 200 response returns success, data.batch, and meta.organizationId. The batch object includes local fileName, status, row counts, progressPercentage, nullable lifecycle timestamps, createdAt, updatedAt, and checkSummary. It does not return row-level CSV data or raw payer payloads.\n\n### Response notes\n- checkSummary aggregates total, eligible, ineligible, pending, and failed checks.\n- startedAt and completedAt may be null until the batch reaches those lifecycle points.\n- The response does not include raw CSV rows, Amazon S3 object contents, or payer payloads.\n\n### Errors and retries\nTreat 404 as missing or unavailable to this organization. Treat 403 as an authorization, scope, or authenticated-organization access failure rather than the normal wrong-ID outcome for a resource lookup. Back off on 429 and retry only transient 5xx responses.\n\n### Error notes\n- 404 can mean the batch does not exist or is outside the authenticated organization.\n- 403 indicates the authenticated API key lacks required access, scope, or organization authorization; wrong-tenant batch IDs should be documented as 404 when the endpoint hides resource existence.\n- 429 requires backoff before polling again.\n","tags":["Eligibility"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"batchId","in":"path","description":"QuickRCM bulk eligibility batch identifier scoped to the authenticated organization."}],"responses":{"200":{"description":"Bulk eligibility batch status for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"batch":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"fileName":{"type":"string"},"status":{"type":"string"},"totalRows":{"type":"integer"},"processedRows":{"type":"integer"},"failedRows":{"type":"integer"},"progressPercentage":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkSummary":{"type":"object","properties":{"total":{"type":"integer"},"eligible":{"type":"integer"},"ineligible":{"type":"integer"},"pending":{"type":"integer"},"failed":{"type":"integer"}},"required":["total","eligible","ineligible","pending","failed"]}},"required":["id","organizationId","fileName","status","totalRows","processedRows","failedRows","progressPercentage","startedAt","completedAt","createdAt","updatedAt","checkSummary"]}},"required":["batch"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"batch":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","fileName":"Example eligibility_batch","status":"active","totalRows":1,"processedRows":1,"failedRows":1,"progressPercentage":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","checkSummary":{"total":1,"eligible":1,"ineligible":1,"pending":1,"failed":1}}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Bulk eligibility batch not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/eligibility/batches/{batchId}/queue":{"post":{"operationId":"queueEligibilityBatch","summary":"Queue bulk eligibility batch","description":"Marks an existing organization-scoped bulk eligibility batch as queued for local worker pickup, with a dry-run response option.\n\n### When to use\nUse this after a batch has been created and validated and the integration is ready to move it into local queued state.\n\n### Before calling\nConfirm the batchId came from the same tenant and that creation or validation succeeded. Use dryRun first when testing automation.\n\n### Request guidance\nSet dryRun to inspect queue behavior without committing the transition. Set queueOnly when the caller wants the local queue-only mode in the 202 response. Neither flag invokes payer APIs inline.\n\n### Request notes\n- batchId is supplied in the path.\n- queueOnly is documented as local worker-pickup state, not inline external processing.\n- dryRun returns a 200 preview response.\n\n### Response semantics\nA 200 response represents a dry-run queue result and returns queue.queued false with local queue mode metadata. A 202 response means the batch was marked queued locally and returns queue.queued true. Neither response means external payer processing has completed.\n\n### Response notes\n- 202 means local queue acceptance for the batch.\n- 200 means a dry-run queue result according to the OpenAPI response description.\n- Implementation currently emits DRY_RUN, QUEUE_ONLY, or QUEUED_FOR_WORKER as queue.mode values; the OpenAPI schema still declares mode as a string, not an enum.\n\n### Errors and retries\nUse 404 to detect missing or wrong-tenant batch IDs, and treat 403 as an authorization, scope, or authenticated-organization access failure. Back off on 429, and avoid retrying a queue transition blindly without checking the batch status first.\n\n### Error notes\n- 404 means the batch is not available in the authenticated organization.\n- 403 indicates the authenticated API key lacks required access, scope, or organization authorization for queueing.\n- 400 indicates invalid queue request shape or lifecycle context.\n- 429 requires backoff before retrying.\n","tags":["Eligibility"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"batchId","in":"path","description":"QuickRCM bulk eligibility batch identifier scoped to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","description":"When true, the handler marks the batch as queued for local worker pickup and returns queue.mode QUEUE_ONLY; no external worker or payer API is invoked inline."},"dryRun":{"type":"boolean","description":"Returns a queue dry-run result without committing the queue transition."}}},"example":{"queueOnly":true,"dryRun":true}}},"description":"Set dryRun to inspect queue behavior without committing the transition. Set queueOnly when the caller wants the local queue-only mode in the 202 response. Neither flag invokes payer APIs inline."},"responses":{"200":{"description":"Bulk eligibility queue dry-run result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"batch":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"fileName":{"type":"string"},"status":{"type":"string"},"totalRows":{"type":"integer"},"processedRows":{"type":"integer"},"failedRows":{"type":"integer"},"progressPercentage":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkSummary":{"type":"object","properties":{"total":{"type":"integer"},"eligible":{"type":"integer"},"ineligible":{"type":"integer"},"pending":{"type":"integer"},"failed":{"type":"integer"}},"required":["total","eligible","ineligible","pending","failed"]}},"required":["id","organizationId","fileName","status","totalRows","processedRows","failedRows","progressPercentage","startedAt","completedAt","createdAt","updatedAt","checkSummary"]},"queue":{"type":"object","properties":{"queued":{"type":"boolean"},"mode":{"type":"string"}},"required":["queued","mode"]}},"required":["batch","queue"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"batch":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","fileName":"Example eligibility_batch","status":"queued","totalRows":1,"processedRows":1,"failedRows":1,"progressPercentage":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","checkSummary":{"total":1,"eligible":1,"ineligible":1,"pending":1,"failed":1}},"queue":{"queued":true,"mode":"example-mode"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Bulk eligibility batch queued locally.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"batch":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"fileName":{"type":"string"},"status":{"type":"string"},"totalRows":{"type":"integer"},"processedRows":{"type":"integer"},"failedRows":{"type":"integer"},"progressPercentage":{"type":"integer"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"checkSummary":{"type":"object","properties":{"total":{"type":"integer"},"eligible":{"type":"integer"},"ineligible":{"type":"integer"},"pending":{"type":"integer"},"failed":{"type":"integer"}},"required":["total","eligible","ineligible","pending","failed"]}},"required":["id","organizationId","fileName","status","totalRows","processedRows","failedRows","progressPercentage","startedAt","completedAt","createdAt","updatedAt","checkSummary"]},"queue":{"type":"object","properties":{"queued":{"type":"boolean"},"mode":{"type":"string"}},"required":["queued","mode"]}},"required":["batch","queue"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"batch":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","fileName":"Example eligibility_batch","status":"queued","totalRows":1,"processedRows":1,"failedRows":1,"progressPercentage":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","checkSummary":{"total":1,"eligible":1,"ineligible":1,"pending":1,"failed":1}},"queue":{"queued":true,"mode":"example-mode"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Bulk eligibility batch not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/claim-status/inquiries":{"post":{"operationId":"createEnhancedStatusApi","summary":"Start enhanced claim status search","description":"Requires claim-status:write scope. Idempotency-Key is optional. If omitted, every submission creates a fresh inquiry with a generated UUID returned as idempotencyKey. Reuse the returned or supplied key for retries of the same request. The latest published mappingProfileId version is pinned at creation.","tags":["Enhanced claim status"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"source":{"type":"string","enum":["standalone"]},"enrichment":{"type":"string","enum":["auto","none","required"],"default":"auto"},"mappingProfileId":{"type":"string","minLength":1,"maxLength":128},"payerId":{"type":"string","minLength":1,"maxLength":128},"provider":{"type":"object","properties":{"npi":{"type":"string","pattern":"^\\d{10}$"},"taxId":{"type":"string","pattern":"^\\d{9}$"},"organizationName":{"type":"string","minLength":1,"maxLength":128}},"required":["npi","organizationName"],"additionalProperties":false},"subscriber":{"type":"object","properties":{"memberId":{"type":"string","minLength":1,"maxLength":128},"firstName":{"type":"string","minLength":1,"maxLength":128},"lastName":{"type":"string","minLength":1,"maxLength":128}},"required":["memberId","firstName","lastName"],"additionalProperties":false},"patient":{"type":"object","properties":{"sameAsSubscriber":{"type":"boolean"},"firstName":{"type":"string","minLength":1,"maxLength":128},"lastName":{"type":"string","minLength":1,"maxLength":128},"memberId":{"type":"string","minLength":1,"maxLength":128},"birthDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["sameAsSubscriber","birthDate"],"additionalProperties":false},"serviceDates":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["from","to"],"additionalProperties":false},"claimNumber":{"type":"string","minLength":1,"maxLength":128},"claimAmount":{"type":"string","pattern":"^\\d+(\\.\\d{1,2})?$"}},"required":["source","payerId","provider","subscriber","patient","serviceDates"],"additionalProperties":false},{"type":"object","properties":{"source":{"type":"string","enum":["existing_claim"]},"enrichment":{"type":"string","enum":["auto","none","required"],"default":"auto"},"mappingProfileId":{"type":"string","minLength":1,"maxLength":128},"claimId":{"type":"string","minLength":1,"maxLength":128},"subscriber":{"type":"object","properties":{"memberId":{"type":"string","minLength":1,"maxLength":128},"firstName":{"type":"string","minLength":1,"maxLength":128},"lastName":{"type":"string","minLength":1,"maxLength":128}},"required":["memberId","firstName","lastName"],"additionalProperties":false}},"required":["source","claimId"],"additionalProperties":false}]},"example":{"source":"standalone","payerId":"87726","provider":{"npi":"1234567893","organizationName":"Example enhanced_status_api","taxId":"12-3456789"},"subscriber":{"memberId":"W123456789","firstName":"John","lastName":"Smith"},"patient":{"sameAsSubscriber":true,"birthDate":"1984-03-22","firstName":"John","lastName":"Smith","memberId":"W123456789"},"serviceDates":{"from":"example-from","to":"example-to"},"enrichment":"auto","mappingProfileId":"00000000-0000-4000-8000-000000000001","claimNumber":"example-claimnumber","claimAmount":"example-claimamount"}}}},"responses":{"202":{"description":"Inquiry accepted or idempotently returned. Poll resultUrl; acceptance does not mean payer success.","content":{"application/json":{"schema":{"type":"object","properties":{"inquiryId":{"type":"string"},"idempotencyKey":{"type":"string","description":"The supplied key or a server-generated UUID. Reuse for retries."},"processingState":{"type":"string"},"mappingProfileVersion":{"type":["integer","null"]},"resultUrl":{"type":"string"}},"required":["inquiryId","idempotencyKey","processingState","mappingProfileVersion","resultUrl"]},"example":{"inquiryId":"00000000-0000-4000-8000-000000000001","idempotencyKey":"example-idempotencykey","processingState":"example-processingstate","mappingProfileVersion":1,"resultUrl":"https://example.quickintell.com/resource"}}}},"400":{"description":"INVALID_REQUEST: invalid body, query, or invalid supplied Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}}}},"401":{"description":"AUTHENTICATION_REQUIRED: bearer key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}}}},"403":{"description":"ACCESS_DENIED: insufficient scope or access","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}}}},"404":{"description":"NOT_FOUND: resource not found within this organization","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}}}},"409":{"description":"REQUEST_CONFLICT: idempotency, mapping, or processing conflict","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}}}},"422":{"description":"REQUEST_UNPROCESSABLE: missing inputs or unpublished profile","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}}}},"429":{"description":"RATE_LIMITED: retry later","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}}}},"500":{"description":"INTERNAL_ERROR: sanitized server error; retry submission with the same Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}}}}}}},"/api/v1/claim-status/inquiries/{id}":{"get":{"operationId":"getEnhancedStatusApi","summary":"Get inquiry processing state","description":"Requires claim-status:read scope. ","tags":["Enhanced claim status"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Processing metadata and outcome. HTTP 200 here does not imply payer success; inspect ok, outcome, and errors.","content":{"application/json":{"schema":{"type":"object","properties":{"inquiryId":{"type":"string"},"processingState":{"type":"string"},"errorCode":{"type":["string","null"]},"resultRevision":{"type":["integer","null"]},"mappingProfileId":{"type":["string","null"]},"mappingProfileVersion":{"type":["integer","null"]},"ok":{"type":"boolean"},"outcome":{"type":"string","enum":["pending","matched","no_match","partial","payer_error","unknown","failed","needs_review"]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["inquiryId","processingState","errorCode","resultRevision","mappingProfileId","mappingProfileVersion","ok","outcome","errors","warnings"]},"example":{"inquiryId":"00000000-0000-4000-8000-000000000001","processingState":"example-processingstate","errorCode":"example-errorcode","resultRevision":1,"mappingProfileId":"00000000-0000-4000-8000-000000000001","mappingProfileVersion":1,"ok":true,"outcome":"pending","errors":[{"code":"ERROR","message":"Request failed","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}],"warnings":[{"code":"ERROR","message":"Request failed","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}]}}}},"400":{"description":"INVALID_REQUEST: invalid body, query, or invalid supplied Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}}}},"401":{"description":"AUTHENTICATION_REQUIRED: bearer key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}}}},"403":{"description":"ACCESS_DENIED: insufficient scope or access","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}}}},"404":{"description":"NOT_FOUND: resource not found within this organization","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}}}},"409":{"description":"REQUEST_CONFLICT: idempotency, mapping, or processing conflict","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}}}},"422":{"description":"REQUEST_UNPROCESSABLE: missing inputs or unpublished profile","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}}}},"429":{"description":"RATE_LIMITED: retry later","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}}}},"500":{"description":"INTERNAL_ERROR: sanitized server error; retry submission with the same Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}}}}}}},"/api/v1/claim-status/inquiries/{id}/result":{"get":{"operationId":"getEnhancedStatusResultApi","summary":"Get saved canonical or mapped result","description":"Requires claim-status:read scope. Default view is canonical. For mapped reports use view=mapped; rows are at data.data.rows. processingState describes worker progress; outcome describes payer/result success. Inspect errors even on HTTP 200. retryable=false means do not blindly resubmit.","tags":["Enhanced claim status"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["canonical","mapped"]},"required":false,"name":"view","in":"query"}],"responses":{"200":{"description":"Matched, no match, or partial result. A partial result can have ok=false and errors alongside usable data.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"outcome":{"type":"string","enum":["pending","matched","no_match","partial","payer_error","unknown","failed","needs_review"]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}},"meta":{"type":"object","properties":{"inquiryId":{"type":"string"},"processingState":{"type":"string"},"errorCode":{"type":["string","null"]},"resultRevision":{"type":["integer","null"]},"mappingProfileId":{"type":["string","null"]},"mappingProfileVersion":{"type":["integer","null"]}},"required":["inquiryId","processingState","errorCode","resultRevision","mappingProfileId","mappingProfileVersion"]},"data":{"anyOf":[{"type":"object","properties":{"schemaVersion":{"type":"string"},"normalizerVersion":{"type":"string"},"outcome":{"type":"string"},"claims":{"type":"array","items":{"type":"object","properties":{"identifiers":{"type":"object","properties":{"payerClaimNumber":{"type":["string","null"]},"patientControlNumber":{"type":["string","null"]}},"required":["payerClaimNumber","patientControlNumber"]},"payer":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["id","name","extensions"]},"patient":{"type":"object","properties":{"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"birthDate":{"type":["string","null"]},"accountNumber":{"type":["string","null"]},"relationshipCode":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["firstName","lastName","memberId","birthDate","accountNumber","relationshipCode","extensions"]},"subscriber":{"type":"object","properties":{"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"birthDate":{"type":["string","null"]},"accountNumber":{"type":["string","null"]},"relationshipCode":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["firstName","lastName","memberId","birthDate","accountNumber","relationshipCode","extensions"]},"providers":{"type":"array","items":{"type":"object","properties":{"npi":{"type":["string","null"]},"taxId":{"type":["string","null"]},"name":{"type":["string","null"]},"role":{"type":["string","null"]},"payerAssignedId":{"type":["string","null"]},"address":{"type":"object","additionalProperties":{}}},"required":["npi","taxId","name","role","payerAssignedId","address"]}},"status":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"payerStatus":{"type":["string","null"]},"details":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]}},"required":["categoryCode","categoryDescription","code","description","effectiveDate"]}}},"required":["categoryCode","categoryDescription","code","description","effectiveDate","payerStatus","details"]},"financials":{"type":"object","properties":{"billed":{"type":["string","null"]},"paid":{"type":["string","null"]},"allowed":{"type":["string","null"]},"deductible":{"type":["string","null"]},"copay":{"type":["string","null"]},"coinsurance":{"type":["string","null"]},"patientResponsibility":{"type":["string","null"]}},"required":["billed","paid","allowed","deductible","copay","coinsurance","patientResponsibility"],"description":"Decimal strings; unavailable amounts are null."},"serviceDates":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]},"receivedDate":{"type":["string","null"]},"finalizedDate":{"type":["string","null"]},"remittances":{"type":"array","items":{}},"serviceLines":{"type":"array","items":{"type":"object","properties":{"lineNumber":{"type":["number","null"]},"controlNumber":{"type":["string","null"]},"procedureCode":{"type":["string","null"]},"revenueCode":{"type":["string","null"]},"quantity":{"type":["string","null"]},"modifiers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":["string","null"]},"slot":{"type":["string","null"]}},"required":["code","description","slot"]}},"status":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"payerStatus":{"type":["string","null"]},"details":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]}},"required":["categoryCode","categoryDescription","code","description","effectiveDate"]}}},"required":["categoryCode","categoryDescription","code","description","effectiveDate","payerStatus","details"]},"financials":{"type":"object","properties":{"billed":{"type":["string","null"]},"paid":{"type":["string","null"]},"allowed":{"type":["string","null"]},"deductible":{"type":["string","null"]},"copay":{"type":["string","null"]},"coinsurance":{"type":["string","null"]},"patientResponsibility":{"type":["string","null"]}},"required":["billed","paid","allowed","deductible","copay","coinsurance","patientResponsibility"],"description":"Decimal strings; unavailable amounts are null."},"serviceDates":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]},"adjustments":{"type":"object","additionalProperties":{}},"remarks":{"type":"array","items":{}},"extensions":{"type":"object","additionalProperties":{}}},"required":["lineNumber","controlNumber","procedureCode","revenueCode","quantity","modifiers","status","financials","serviceDates","adjustments","remarks","extensions"]}},"serviceLinesAvailability":{"type":"string","enum":["reported","not_reported"]},"eligibleForValueAdds":{"type":["boolean","null"]},"enrichmentState":{"type":"string"},"extensions":{"type":"object","additionalProperties":{}},"provenance":{"type":"object","additionalProperties":{"type":"object","properties":{"exchangeId":{"type":"string"},"path":{"type":"string"}},"required":["exchangeId","path"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}}},"required":["identifiers","payer","patient","subscriber","providers","status","financials","serviceDates","receivedDate","finalizedDate","remittances","serviceLines","serviceLinesAvailability","eligibleForValueAdds","enrichmentState","extensions","provenance","issues"]}},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":["string","null"]},"level":{"type":["string","null"]},"message":{"type":["string","null"]}},"required":["code","level","message"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}},"incomplete":{"type":"boolean"},"sourceExchangeIds":{"type":"array","items":{"type":"string"}}},"required":["schemaVersion","normalizerVersion","outcome","claims","errors","issues","incomplete","sourceExchangeIds"]},{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["rows"]},{"type":"object","properties":{"claims":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["claims"]}]},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}},"state":{"type":"string","enum":["valid","invalid"]}},"required":["data","issues","state"],"description":"Custom keys follow the pinned profile. Flat report rows are at response.data.data.rows; nested claims at response.data.data.claims."},{"type":"null"}]}},"required":["ok","outcome","errors","warnings","meta","data"]},"example":{"ok":true,"outcome":"pending","errors":[{"code":"ERROR","message":"Request failed","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}],"warnings":[{"code":"ERROR","message":"Request failed","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}],"meta":{"inquiryId":"00000000-0000-4000-8000-000000000001","processingState":"example-processingstate","errorCode":"example-errorcode","resultRevision":1,"mappingProfileId":"00000000-0000-4000-8000-000000000001","mappingProfileVersion":1},"data":{"schemaVersion":"example-schemaversion","normalizerVersion":"example-normalizerversion","outcome":"example-outcome","claims":[{"identifiers":{"payerClaimNumber":"example-payerclaimnumber","patientControlNumber":"example-patientcontrolnumber"},"payer":{"id":"00000000-0000-4000-8000-000000000001","name":"Example enhanced_status_result_api","extensions":{}},"patient":{"firstName":"John","lastName":"Smith","memberId":"W123456789","birthDate":"1984-03-22","accountNumber":"example-accountnumber","relationshipCode":"example-relationshipcode","extensions":{}},"subscriber":{"firstName":"John","lastName":"Smith","memberId":"W123456789","birthDate":"1984-03-22","accountNumber":"example-accountnumber","relationshipCode":"example-relationshipcode","extensions":{}},"providers":[{"npi":"1234567893","taxId":"12-3456789","name":"Example enhanced_status_result_api","role":"example-role","payerAssignedId":"00000000-0000-4000-8000-000000000001","address":{}}],"status":{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08","payerStatus":"example-payerstatus","details":[{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08"}]},"financials":{"billed":"example-billed","paid":"00000000-0000-4000-8000-000000000001","allowed":"example-allowed","deductible":"example-deductible","copay":"example-copay","coinsurance":"example-coinsurance","patientResponsibility":"example-patientresponsibility"},"serviceDates":{"from":"example-from","to":"example-to"},"receivedDate":"2026-06-08","finalizedDate":"2026-06-08","remittances":["example-remittances"],"serviceLines":[{"lineNumber":1.25,"controlNumber":"example-controlnumber","procedureCode":"example-procedurecode","revenueCode":"example-revenuecode","quantity":"example-quantity","modifiers":[{"code":"ERROR","description":"Example enhanced_status_result_api note","slot":"example-slot"}],"status":{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08","payerStatus":"example-payerstatus","details":[{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08"}]},"financials":{"billed":"example-billed","paid":"00000000-0000-4000-8000-000000000001","allowed":"example-allowed","deductible":"example-deductible","copay":"example-copay","coinsurance":"example-coinsurance","patientResponsibility":"example-patientresponsibility"},"serviceDates":{"from":"example-from","to":"example-to"},"adjustments":{},"remarks":["example-remarks"],"extensions":{}}],"serviceLinesAvailability":"reported","eligibleForValueAdds":true,"enrichmentState":"example-enrichmentstate","extensions":{},"provenance":{},"issues":[{"code":"ERROR","path":"example-path","severity":"info"}]}],"errors":[{"code":"ERROR","level":"example-level","message":"Request failed"}],"issues":[{"code":"ERROR","path":"example-path","severity":"info"}],"incomplete":true,"sourceExchangeIds":["example-sourceexchangeids"]}}}}},"202":{"description":"Still queued/searching/enriching: ok=false, outcome=pending. Data may be null or interim; poll this URL.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"outcome":{"type":"string","enum":["pending","matched","no_match","partial","payer_error","unknown","failed","needs_review"]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}},"meta":{"type":"object","properties":{"inquiryId":{"type":"string"},"processingState":{"type":"string"},"errorCode":{"type":["string","null"]},"resultRevision":{"type":["integer","null"]},"mappingProfileId":{"type":["string","null"]},"mappingProfileVersion":{"type":["integer","null"]}},"required":["inquiryId","processingState","errorCode","resultRevision","mappingProfileId","mappingProfileVersion"]},"data":{"anyOf":[{"type":"object","properties":{"schemaVersion":{"type":"string"},"normalizerVersion":{"type":"string"},"outcome":{"type":"string"},"claims":{"type":"array","items":{"type":"object","properties":{"identifiers":{"type":"object","properties":{"payerClaimNumber":{"type":["string","null"]},"patientControlNumber":{"type":["string","null"]}},"required":["payerClaimNumber","patientControlNumber"]},"payer":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["id","name","extensions"]},"patient":{"type":"object","properties":{"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"birthDate":{"type":["string","null"]},"accountNumber":{"type":["string","null"]},"relationshipCode":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["firstName","lastName","memberId","birthDate","accountNumber","relationshipCode","extensions"]},"subscriber":{"type":"object","properties":{"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"birthDate":{"type":["string","null"]},"accountNumber":{"type":["string","null"]},"relationshipCode":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["firstName","lastName","memberId","birthDate","accountNumber","relationshipCode","extensions"]},"providers":{"type":"array","items":{"type":"object","properties":{"npi":{"type":["string","null"]},"taxId":{"type":["string","null"]},"name":{"type":["string","null"]},"role":{"type":["string","null"]},"payerAssignedId":{"type":["string","null"]},"address":{"type":"object","additionalProperties":{}}},"required":["npi","taxId","name","role","payerAssignedId","address"]}},"status":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"payerStatus":{"type":["string","null"]},"details":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]}},"required":["categoryCode","categoryDescription","code","description","effectiveDate"]}}},"required":["categoryCode","categoryDescription","code","description","effectiveDate","payerStatus","details"]},"financials":{"type":"object","properties":{"billed":{"type":["string","null"]},"paid":{"type":["string","null"]},"allowed":{"type":["string","null"]},"deductible":{"type":["string","null"]},"copay":{"type":["string","null"]},"coinsurance":{"type":["string","null"]},"patientResponsibility":{"type":["string","null"]}},"required":["billed","paid","allowed","deductible","copay","coinsurance","patientResponsibility"],"description":"Decimal strings; unavailable amounts are null."},"serviceDates":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]},"receivedDate":{"type":["string","null"]},"finalizedDate":{"type":["string","null"]},"remittances":{"type":"array","items":{}},"serviceLines":{"type":"array","items":{"type":"object","properties":{"lineNumber":{"type":["number","null"]},"controlNumber":{"type":["string","null"]},"procedureCode":{"type":["string","null"]},"revenueCode":{"type":["string","null"]},"quantity":{"type":["string","null"]},"modifiers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":["string","null"]},"slot":{"type":["string","null"]}},"required":["code","description","slot"]}},"status":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"payerStatus":{"type":["string","null"]},"details":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]}},"required":["categoryCode","categoryDescription","code","description","effectiveDate"]}}},"required":["categoryCode","categoryDescription","code","description","effectiveDate","payerStatus","details"]},"financials":{"type":"object","properties":{"billed":{"type":["string","null"]},"paid":{"type":["string","null"]},"allowed":{"type":["string","null"]},"deductible":{"type":["string","null"]},"copay":{"type":["string","null"]},"coinsurance":{"type":["string","null"]},"patientResponsibility":{"type":["string","null"]}},"required":["billed","paid","allowed","deductible","copay","coinsurance","patientResponsibility"],"description":"Decimal strings; unavailable amounts are null."},"serviceDates":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]},"adjustments":{"type":"object","additionalProperties":{}},"remarks":{"type":"array","items":{}},"extensions":{"type":"object","additionalProperties":{}}},"required":["lineNumber","controlNumber","procedureCode","revenueCode","quantity","modifiers","status","financials","serviceDates","adjustments","remarks","extensions"]}},"serviceLinesAvailability":{"type":"string","enum":["reported","not_reported"]},"eligibleForValueAdds":{"type":["boolean","null"]},"enrichmentState":{"type":"string"},"extensions":{"type":"object","additionalProperties":{}},"provenance":{"type":"object","additionalProperties":{"type":"object","properties":{"exchangeId":{"type":"string"},"path":{"type":"string"}},"required":["exchangeId","path"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}}},"required":["identifiers","payer","patient","subscriber","providers","status","financials","serviceDates","receivedDate","finalizedDate","remittances","serviceLines","serviceLinesAvailability","eligibleForValueAdds","enrichmentState","extensions","provenance","issues"]}},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":["string","null"]},"level":{"type":["string","null"]},"message":{"type":["string","null"]}},"required":["code","level","message"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}},"incomplete":{"type":"boolean"},"sourceExchangeIds":{"type":"array","items":{"type":"string"}}},"required":["schemaVersion","normalizerVersion","outcome","claims","errors","issues","incomplete","sourceExchangeIds"]},{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["rows"]},{"type":"object","properties":{"claims":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["claims"]}]},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}},"state":{"type":"string","enum":["valid","invalid"]}},"required":["data","issues","state"],"description":"Custom keys follow the pinned profile. Flat report rows are at response.data.data.rows; nested claims at response.data.data.claims."},{"type":"null"}]}},"required":["ok","outcome","errors","warnings","meta","data"]},"example":{"ok":true,"outcome":"pending","errors":[{"code":"ERROR","message":"Request failed","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}],"warnings":[{"code":"ERROR","message":"Request failed","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}],"meta":{"inquiryId":"00000000-0000-4000-8000-000000000001","processingState":"example-processingstate","errorCode":"example-errorcode","resultRevision":1,"mappingProfileId":"00000000-0000-4000-8000-000000000001","mappingProfileVersion":1},"data":{"schemaVersion":"example-schemaversion","normalizerVersion":"example-normalizerversion","outcome":"example-outcome","claims":[{"identifiers":{"payerClaimNumber":"example-payerclaimnumber","patientControlNumber":"example-patientcontrolnumber"},"payer":{"id":"00000000-0000-4000-8000-000000000001","name":"Example enhanced_status_result_api","extensions":{}},"patient":{"firstName":"John","lastName":"Smith","memberId":"W123456789","birthDate":"1984-03-22","accountNumber":"example-accountnumber","relationshipCode":"example-relationshipcode","extensions":{}},"subscriber":{"firstName":"John","lastName":"Smith","memberId":"W123456789","birthDate":"1984-03-22","accountNumber":"example-accountnumber","relationshipCode":"example-relationshipcode","extensions":{}},"providers":[{"npi":"1234567893","taxId":"12-3456789","name":"Example enhanced_status_result_api","role":"example-role","payerAssignedId":"00000000-0000-4000-8000-000000000001","address":{}}],"status":{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08","payerStatus":"example-payerstatus","details":[{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08"}]},"financials":{"billed":"example-billed","paid":"00000000-0000-4000-8000-000000000001","allowed":"example-allowed","deductible":"example-deductible","copay":"example-copay","coinsurance":"example-coinsurance","patientResponsibility":"example-patientresponsibility"},"serviceDates":{"from":"example-from","to":"example-to"},"receivedDate":"2026-06-08","finalizedDate":"2026-06-08","remittances":["example-remittances"],"serviceLines":[{"lineNumber":1.25,"controlNumber":"example-controlnumber","procedureCode":"example-procedurecode","revenueCode":"example-revenuecode","quantity":"example-quantity","modifiers":[{"code":"ERROR","description":"Example enhanced_status_result_api note","slot":"example-slot"}],"status":{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08","payerStatus":"example-payerstatus","details":[{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08"}]},"financials":{"billed":"example-billed","paid":"00000000-0000-4000-8000-000000000001","allowed":"example-allowed","deductible":"example-deductible","copay":"example-copay","coinsurance":"example-coinsurance","patientResponsibility":"example-patientresponsibility"},"serviceDates":{"from":"example-from","to":"example-to"},"adjustments":{},"remarks":["example-remarks"],"extensions":{}}],"serviceLinesAvailability":"reported","eligibleForValueAdds":true,"enrichmentState":"example-enrichmentstate","extensions":{},"provenance":{},"issues":[{"code":"ERROR","path":"example-path","severity":"info"}]}],"errors":[{"code":"ERROR","level":"example-level","message":"Request failed"}],"issues":[{"code":"ERROR","path":"example-path","severity":"info"}],"incomplete":true,"sourceExchangeIds":["example-sourceexchangeids"]}}}}},"400":{"description":"INVALID_REQUEST: invalid body, query, or invalid supplied Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}}}},"401":{"description":"AUTHENTICATION_REQUIRED: bearer key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}}}},"403":{"description":"ACCESS_DENIED: insufficient scope or access","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}}}},"404":{"description":"NOT_FOUND: resource not found within this organization","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}}}},"409":{"description":"Needs review (result envelope) or missing mapping/conflict (API error envelope). Do not automatically resubmit an uncertain payer submission.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean"},"outcome":{"type":"string","enum":["pending","matched","no_match","partial","payer_error","unknown","failed","needs_review"]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}},"meta":{"type":"object","properties":{"inquiryId":{"type":"string"},"processingState":{"type":"string"},"errorCode":{"type":["string","null"]},"resultRevision":{"type":["integer","null"]},"mappingProfileId":{"type":["string","null"]},"mappingProfileVersion":{"type":["integer","null"]}},"required":["inquiryId","processingState","errorCode","resultRevision","mappingProfileId","mappingProfileVersion"]},"data":{"anyOf":[{"type":"object","properties":{"schemaVersion":{"type":"string"},"normalizerVersion":{"type":"string"},"outcome":{"type":"string"},"claims":{"type":"array","items":{"type":"object","properties":{"identifiers":{"type":"object","properties":{"payerClaimNumber":{"type":["string","null"]},"patientControlNumber":{"type":["string","null"]}},"required":["payerClaimNumber","patientControlNumber"]},"payer":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["id","name","extensions"]},"patient":{"type":"object","properties":{"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"birthDate":{"type":["string","null"]},"accountNumber":{"type":["string","null"]},"relationshipCode":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["firstName","lastName","memberId","birthDate","accountNumber","relationshipCode","extensions"]},"subscriber":{"type":"object","properties":{"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"birthDate":{"type":["string","null"]},"accountNumber":{"type":["string","null"]},"relationshipCode":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["firstName","lastName","memberId","birthDate","accountNumber","relationshipCode","extensions"]},"providers":{"type":"array","items":{"type":"object","properties":{"npi":{"type":["string","null"]},"taxId":{"type":["string","null"]},"name":{"type":["string","null"]},"role":{"type":["string","null"]},"payerAssignedId":{"type":["string","null"]},"address":{"type":"object","additionalProperties":{}}},"required":["npi","taxId","name","role","payerAssignedId","address"]}},"status":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"payerStatus":{"type":["string","null"]},"details":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]}},"required":["categoryCode","categoryDescription","code","description","effectiveDate"]}}},"required":["categoryCode","categoryDescription","code","description","effectiveDate","payerStatus","details"]},"financials":{"type":"object","properties":{"billed":{"type":["string","null"]},"paid":{"type":["string","null"]},"allowed":{"type":["string","null"]},"deductible":{"type":["string","null"]},"copay":{"type":["string","null"]},"coinsurance":{"type":["string","null"]},"patientResponsibility":{"type":["string","null"]}},"required":["billed","paid","allowed","deductible","copay","coinsurance","patientResponsibility"],"description":"Decimal strings; unavailable amounts are null."},"serviceDates":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]},"receivedDate":{"type":["string","null"]},"finalizedDate":{"type":["string","null"]},"remittances":{"type":"array","items":{}},"serviceLines":{"type":"array","items":{"type":"object","properties":{"lineNumber":{"type":["number","null"]},"controlNumber":{"type":["string","null"]},"procedureCode":{"type":["string","null"]},"revenueCode":{"type":["string","null"]},"quantity":{"type":["string","null"]},"modifiers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":["string","null"]},"slot":{"type":["string","null"]}},"required":["code","description","slot"]}},"status":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"payerStatus":{"type":["string","null"]},"details":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]}},"required":["categoryCode","categoryDescription","code","description","effectiveDate"]}}},"required":["categoryCode","categoryDescription","code","description","effectiveDate","payerStatus","details"]},"financials":{"type":"object","properties":{"billed":{"type":["string","null"]},"paid":{"type":["string","null"]},"allowed":{"type":["string","null"]},"deductible":{"type":["string","null"]},"copay":{"type":["string","null"]},"coinsurance":{"type":["string","null"]},"patientResponsibility":{"type":["string","null"]}},"required":["billed","paid","allowed","deductible","copay","coinsurance","patientResponsibility"],"description":"Decimal strings; unavailable amounts are null."},"serviceDates":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]},"adjustments":{"type":"object","additionalProperties":{}},"remarks":{"type":"array","items":{}},"extensions":{"type":"object","additionalProperties":{}}},"required":["lineNumber","controlNumber","procedureCode","revenueCode","quantity","modifiers","status","financials","serviceDates","adjustments","remarks","extensions"]}},"serviceLinesAvailability":{"type":"string","enum":["reported","not_reported"]},"eligibleForValueAdds":{"type":["boolean","null"]},"enrichmentState":{"type":"string"},"extensions":{"type":"object","additionalProperties":{}},"provenance":{"type":"object","additionalProperties":{"type":"object","properties":{"exchangeId":{"type":"string"},"path":{"type":"string"}},"required":["exchangeId","path"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}}},"required":["identifiers","payer","patient","subscriber","providers","status","financials","serviceDates","receivedDate","finalizedDate","remittances","serviceLines","serviceLinesAvailability","eligibleForValueAdds","enrichmentState","extensions","provenance","issues"]}},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":["string","null"]},"level":{"type":["string","null"]},"message":{"type":["string","null"]}},"required":["code","level","message"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}},"incomplete":{"type":"boolean"},"sourceExchangeIds":{"type":"array","items":{"type":"string"}}},"required":["schemaVersion","normalizerVersion","outcome","claims","errors","issues","incomplete","sourceExchangeIds"]},{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["rows"]},{"type":"object","properties":{"claims":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["claims"]}]},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}},"state":{"type":"string","enum":["valid","invalid"]}},"required":["data","issues","state"],"description":"Custom keys follow the pinned profile. Flat report rows are at response.data.data.rows; nested claims at response.data.data.claims."},{"type":"null"}]}},"required":["ok","outcome","errors","warnings","meta","data"]},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"]}]},"example":{"ok":true,"outcome":"pending","errors":[{"code":"CONFLICT","message":"Resource conflict","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}],"warnings":[{"code":"CONFLICT","message":"Resource conflict","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}],"meta":{"inquiryId":"00000000-0000-4000-8000-000000000001","processingState":"example-processingstate","errorCode":"example-errorcode","resultRevision":1,"mappingProfileId":"00000000-0000-4000-8000-000000000001","mappingProfileVersion":1},"data":{"schemaVersion":"example-schemaversion","normalizerVersion":"example-normalizerversion","outcome":"example-outcome","claims":[{"identifiers":{"payerClaimNumber":"example-payerclaimnumber","patientControlNumber":"example-patientcontrolnumber"},"payer":{"id":"00000000-0000-4000-8000-000000000001","name":"Example enhanced_status_result_api","extensions":{}},"patient":{"firstName":"John","lastName":"Smith","memberId":"W123456789","birthDate":"1984-03-22","accountNumber":"example-accountnumber","relationshipCode":"example-relationshipcode","extensions":{}},"subscriber":{"firstName":"John","lastName":"Smith","memberId":"W123456789","birthDate":"1984-03-22","accountNumber":"example-accountnumber","relationshipCode":"example-relationshipcode","extensions":{}},"providers":[{"npi":"1234567893","taxId":"12-3456789","name":"Example enhanced_status_result_api","role":"example-role","payerAssignedId":"00000000-0000-4000-8000-000000000001","address":{}}],"status":{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"CONFLICT","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08","payerStatus":"example-payerstatus","details":[{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"CONFLICT","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08"}]},"financials":{"billed":"example-billed","paid":"00000000-0000-4000-8000-000000000001","allowed":"example-allowed","deductible":"example-deductible","copay":"example-copay","coinsurance":"example-coinsurance","patientResponsibility":"example-patientresponsibility"},"serviceDates":{"from":"example-from","to":"example-to"},"receivedDate":"2026-06-08","finalizedDate":"2026-06-08","remittances":["example-remittances"],"serviceLines":[{"lineNumber":1.25,"controlNumber":"example-controlnumber","procedureCode":"example-procedurecode","revenueCode":"example-revenuecode","quantity":"example-quantity","modifiers":[{"code":"CONFLICT","description":"Example enhanced_status_result_api note","slot":"example-slot"}],"status":{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"CONFLICT","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08","payerStatus":"example-payerstatus","details":[{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"CONFLICT","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08"}]},"financials":{"billed":"example-billed","paid":"00000000-0000-4000-8000-000000000001","allowed":"example-allowed","deductible":"example-deductible","copay":"example-copay","coinsurance":"example-coinsurance","patientResponsibility":"example-patientresponsibility"},"serviceDates":{"from":"example-from","to":"example-to"},"adjustments":{},"remarks":["example-remarks"],"extensions":{}}],"serviceLinesAvailability":"reported","eligibleForValueAdds":true,"enrichmentState":"example-enrichmentstate","extensions":{},"provenance":{},"issues":[{"code":"CONFLICT","path":"example-path","severity":"info"}]}],"errors":[{"code":"CONFLICT","level":"example-level","message":"Resource conflict"}],"issues":[{"code":"CONFLICT","path":"example-path","severity":"info"}],"incomplete":true,"sourceExchangeIds":["example-sourceexchangeids"]}}}}},"422":{"description":"Terminal payer/processing failure (result envelope), or request rejected (API error envelope). Inspect errors[].","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean"},"outcome":{"type":"string","enum":["pending","matched","no_match","partial","payer_error","unknown","failed","needs_review"]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}},"meta":{"type":"object","properties":{"inquiryId":{"type":"string"},"processingState":{"type":"string"},"errorCode":{"type":["string","null"]},"resultRevision":{"type":["integer","null"]},"mappingProfileId":{"type":["string","null"]},"mappingProfileVersion":{"type":["integer","null"]}},"required":["inquiryId","processingState","errorCode","resultRevision","mappingProfileId","mappingProfileVersion"]},"data":{"anyOf":[{"type":"object","properties":{"schemaVersion":{"type":"string"},"normalizerVersion":{"type":"string"},"outcome":{"type":"string"},"claims":{"type":"array","items":{"type":"object","properties":{"identifiers":{"type":"object","properties":{"payerClaimNumber":{"type":["string","null"]},"patientControlNumber":{"type":["string","null"]}},"required":["payerClaimNumber","patientControlNumber"]},"payer":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["id","name","extensions"]},"patient":{"type":"object","properties":{"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"birthDate":{"type":["string","null"]},"accountNumber":{"type":["string","null"]},"relationshipCode":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["firstName","lastName","memberId","birthDate","accountNumber","relationshipCode","extensions"]},"subscriber":{"type":"object","properties":{"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"birthDate":{"type":["string","null"]},"accountNumber":{"type":["string","null"]},"relationshipCode":{"type":["string","null"]},"extensions":{"type":"object","additionalProperties":{}}},"required":["firstName","lastName","memberId","birthDate","accountNumber","relationshipCode","extensions"]},"providers":{"type":"array","items":{"type":"object","properties":{"npi":{"type":["string","null"]},"taxId":{"type":["string","null"]},"name":{"type":["string","null"]},"role":{"type":["string","null"]},"payerAssignedId":{"type":["string","null"]},"address":{"type":"object","additionalProperties":{}}},"required":["npi","taxId","name","role","payerAssignedId","address"]}},"status":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"payerStatus":{"type":["string","null"]},"details":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]}},"required":["categoryCode","categoryDescription","code","description","effectiveDate"]}}},"required":["categoryCode","categoryDescription","code","description","effectiveDate","payerStatus","details"]},"financials":{"type":"object","properties":{"billed":{"type":["string","null"]},"paid":{"type":["string","null"]},"allowed":{"type":["string","null"]},"deductible":{"type":["string","null"]},"copay":{"type":["string","null"]},"coinsurance":{"type":["string","null"]},"patientResponsibility":{"type":["string","null"]}},"required":["billed","paid","allowed","deductible","copay","coinsurance","patientResponsibility"],"description":"Decimal strings; unavailable amounts are null."},"serviceDates":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]},"receivedDate":{"type":["string","null"]},"finalizedDate":{"type":["string","null"]},"remittances":{"type":"array","items":{}},"serviceLines":{"type":"array","items":{"type":"object","properties":{"lineNumber":{"type":["number","null"]},"controlNumber":{"type":["string","null"]},"procedureCode":{"type":["string","null"]},"revenueCode":{"type":["string","null"]},"quantity":{"type":["string","null"]},"modifiers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":["string","null"]},"slot":{"type":["string","null"]}},"required":["code","description","slot"]}},"status":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]},"payerStatus":{"type":["string","null"]},"details":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":["string","null"]},"categoryDescription":{"type":["string","null"]},"code":{"type":["string","null"]},"description":{"type":["string","null"]},"effectiveDate":{"type":["string","null"]}},"required":["categoryCode","categoryDescription","code","description","effectiveDate"]}}},"required":["categoryCode","categoryDescription","code","description","effectiveDate","payerStatus","details"]},"financials":{"type":"object","properties":{"billed":{"type":["string","null"]},"paid":{"type":["string","null"]},"allowed":{"type":["string","null"]},"deductible":{"type":["string","null"]},"copay":{"type":["string","null"]},"coinsurance":{"type":["string","null"]},"patientResponsibility":{"type":["string","null"]}},"required":["billed","paid","allowed","deductible","copay","coinsurance","patientResponsibility"],"description":"Decimal strings; unavailable amounts are null."},"serviceDates":{"type":"object","properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]}},"required":["from","to"]},"adjustments":{"type":"object","additionalProperties":{}},"remarks":{"type":"array","items":{}},"extensions":{"type":"object","additionalProperties":{}}},"required":["lineNumber","controlNumber","procedureCode","revenueCode","quantity","modifiers","status","financials","serviceDates","adjustments","remarks","extensions"]}},"serviceLinesAvailability":{"type":"string","enum":["reported","not_reported"]},"eligibleForValueAdds":{"type":["boolean","null"]},"enrichmentState":{"type":"string"},"extensions":{"type":"object","additionalProperties":{}},"provenance":{"type":"object","additionalProperties":{"type":"object","properties":{"exchangeId":{"type":"string"},"path":{"type":"string"}},"required":["exchangeId","path"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}}},"required":["identifiers","payer","patient","subscriber","providers","status","financials","serviceDates","receivedDate","finalizedDate","remittances","serviceLines","serviceLinesAvailability","eligibleForValueAdds","enrichmentState","extensions","provenance","issues"]}},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":["string","null"]},"level":{"type":["string","null"]},"message":{"type":["string","null"]}},"required":["code","level","message"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}},"incomplete":{"type":"boolean"},"sourceExchangeIds":{"type":"array","items":{"type":"string"}}},"required":["schemaVersion","normalizerVersion","outcome","claims","errors","issues","incomplete","sourceExchangeIds"]},{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["rows"]},{"type":"object","properties":{"claims":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["claims"]}]},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]}},"required":["code","path","severity"]}},"state":{"type":"string","enum":["valid","invalid"]}},"required":["data","issues","state"],"description":"Custom keys follow the pinned profile. Flat report rows are at response.data.data.rows; nested claims at response.data.data.claims."},{"type":"null"}]}},"required":["ok","outcome","errors","warnings","meta","data"]},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"]}]},"example":{"ok":true,"outcome":"pending","errors":[{"code":"ERROR","message":"Request failed","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}],"warnings":[{"code":"ERROR","message":"Request failed","source":"example-source","retryable":true,"stage":"example-stage","claimIndex":1,"httpStatus":1,"path":"example-path"}],"meta":{"inquiryId":"00000000-0000-4000-8000-000000000001","processingState":"example-processingstate","errorCode":"example-errorcode","resultRevision":1,"mappingProfileId":"00000000-0000-4000-8000-000000000001","mappingProfileVersion":1},"data":{"schemaVersion":"example-schemaversion","normalizerVersion":"example-normalizerversion","outcome":"example-outcome","claims":[{"identifiers":{"payerClaimNumber":"example-payerclaimnumber","patientControlNumber":"example-patientcontrolnumber"},"payer":{"id":"00000000-0000-4000-8000-000000000001","name":"Example enhanced_status_result_api","extensions":{}},"patient":{"firstName":"John","lastName":"Smith","memberId":"W123456789","birthDate":"1984-03-22","accountNumber":"example-accountnumber","relationshipCode":"example-relationshipcode","extensions":{}},"subscriber":{"firstName":"John","lastName":"Smith","memberId":"W123456789","birthDate":"1984-03-22","accountNumber":"example-accountnumber","relationshipCode":"example-relationshipcode","extensions":{}},"providers":[{"npi":"1234567893","taxId":"12-3456789","name":"Example enhanced_status_result_api","role":"example-role","payerAssignedId":"00000000-0000-4000-8000-000000000001","address":{}}],"status":{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08","payerStatus":"example-payerstatus","details":[{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08"}]},"financials":{"billed":"example-billed","paid":"00000000-0000-4000-8000-000000000001","allowed":"example-allowed","deductible":"example-deductible","copay":"example-copay","coinsurance":"example-coinsurance","patientResponsibility":"example-patientresponsibility"},"serviceDates":{"from":"example-from","to":"example-to"},"receivedDate":"2026-06-08","finalizedDate":"2026-06-08","remittances":["example-remittances"],"serviceLines":[{"lineNumber":1.25,"controlNumber":"example-controlnumber","procedureCode":"example-procedurecode","revenueCode":"example-revenuecode","quantity":"example-quantity","modifiers":[{"code":"ERROR","description":"Example enhanced_status_result_api note","slot":"example-slot"}],"status":{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08","payerStatus":"example-payerstatus","details":[{"categoryCode":"example-categorycode","categoryDescription":"Example enhanced_status_result_api note","code":"ERROR","description":"Example enhanced_status_result_api note","effectiveDate":"2026-06-08"}]},"financials":{"billed":"example-billed","paid":"00000000-0000-4000-8000-000000000001","allowed":"example-allowed","deductible":"example-deductible","copay":"example-copay","coinsurance":"example-coinsurance","patientResponsibility":"example-patientresponsibility"},"serviceDates":{"from":"example-from","to":"example-to"},"adjustments":{},"remarks":["example-remarks"],"extensions":{}}],"serviceLinesAvailability":"reported","eligibleForValueAdds":true,"enrichmentState":"example-enrichmentstate","extensions":{},"provenance":{},"issues":[{"code":"ERROR","path":"example-path","severity":"info"}]}],"errors":[{"code":"ERROR","level":"example-level","message":"Request failed"}],"issues":[{"code":"ERROR","path":"example-path","severity":"info"}],"incomplete":true,"sourceExchangeIds":["example-sourceexchangeids"]}}}}},"429":{"description":"RATE_LIMITED: retry later","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}}}},"500":{"description":"INTERNAL_ERROR: sanitized server error; retry submission with the same Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}}}}}}},"/api/v1/claim-status/inquiries/{id}/raw":{"get":{"operationId":"getEnhancedStatusRawApi","summary":"Get restricted raw response history","description":"Requires claim-status:raw scope. ","tags":["Enhanced claim status"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Raw exchange history (up to 250 records), ordered oldest first.","content":{"application/json":{"schema":{"type":"object","properties":{"inquiryId":{"type":"string"},"exchanges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"payerId":{"type":"string"},"transactionId":{"type":"string"},"method":{"type":"string"},"status":{"type":["integer","null"]},"body":{"type":["string","null"],"description":"Stored response bytes decoded as UTF-8; may contain non-JSON vendor errors."},"bodyHash":{"type":["string","null"]},"contentType":{"type":["string","null"]},"retryAfter":{"type":["string","null"]},"errorCode":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"receivedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","payerId","transactionId","method","status","body","bodyHash","contentType","retryAfter","errorCode","createdAt","receivedAt"]}}},"required":["inquiryId","exchanges"]},"example":{"inquiryId":"00000000-0000-4000-8000-000000000001","exchanges":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","payerId":"87726","transactionId":"00000000-0000-4000-8000-000000000001","method":"example-method","status":1,"body":"example-body","bodyHash":"example-bodyhash","contentType":"example-contenttype","retryAfter":"example-retryafter","errorCode":"example-errorcode","createdAt":"2026-06-08T10:15:30Z","receivedAt":"2026-06-08T10:15:30Z"}]}}}},"400":{"description":"INVALID_REQUEST: invalid body, query, or invalid supplied Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}}}},"401":{"description":"AUTHENTICATION_REQUIRED: bearer key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}}}},"403":{"description":"ACCESS_DENIED: insufficient scope or access","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}}}},"404":{"description":"NOT_FOUND: resource not found within this organization","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}}}},"409":{"description":"REQUEST_CONFLICT: idempotency, mapping, or processing conflict","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}}}},"422":{"description":"REQUEST_UNPROCESSABLE: missing inputs or unpublished profile","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}}}},"429":{"description":"RATE_LIMITED: retry later","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}}}},"500":{"description":"INTERNAL_ERROR: sanitized server error; retry submission with the same Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}}}}}}},"/api/v1/claim-status/inquiries/{id}/reprocess":{"post":{"operationId":"reprocessEnhancedStatusApi","summary":"Replay saved responses without a payer call","description":"Requires claim-status:write scope. ","tags":["Enhanced claim status"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"New saved result revision; no new payer call.","content":{"application/json":{"schema":{"type":"object","properties":{"inquiryId":{"type":"string"},"revision":{"type":"integer"}},"required":["inquiryId","revision"]},"example":{"inquiryId":"00000000-0000-4000-8000-000000000001","revision":1}}}},"400":{"description":"INVALID_REQUEST: invalid body, query, or invalid supplied Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}}}},"401":{"description":"AUTHENTICATION_REQUIRED: bearer key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}}}},"403":{"description":"ACCESS_DENIED: insufficient scope or access","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}}}},"404":{"description":"NOT_FOUND: resource not found within this organization","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}}}},"409":{"description":"REQUEST_CONFLICT: idempotency, mapping, or processing conflict","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}}}},"422":{"description":"REQUEST_UNPROCESSABLE: missing inputs or unpublished profile","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}}}},"429":{"description":"RATE_LIMITED: retry later","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}}}},"500":{"description":"INTERNAL_ERROR: sanitized server error; retry submission with the same Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}}}}}}},"/api/v1/claim-status/profiles":{"get":{"operationId":"listEnhancedStatusProfilesApi","summary":"List organization mapping profiles","description":"Requires claim-status:read scope. ","tags":["Enhanced claim status"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Organization profiles (up to 100), most recently updated first.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"draft":{"type":"object","properties":{"layout":{"type":"string","enum":["nested","flat_rows"],"default":"nested"},"includeClaimSummary":{"type":"boolean","default":true},"rules":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["canonical","search","valueAdds","context","constant"]},"scope":{"type":"string","enum":["claim","serviceLine"],"default":"claim"},"sourcePath":{"type":"string","maxLength":256,"pattern":"^\\$(?:\\.[A-Za-z_][A-Za-z0-9_]*|\\[\\d+\\])*$"},"targetPath":{"type":"string","maxLength":256,"pattern":"^[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)*$"},"constantValue":{"anyOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}]},"payerId":{"type":"string","maxLength":64},"type":{"type":"string","enum":["string","decimal_string","boolean","json"],"default":"string"},"transform":{"type":"string","enum":["none","trim","uppercase","lowercase","date_ddmmyyyy","currency_usd","modifier_codes","modifier_descriptions"],"default":"none"},"required":{"type":"boolean","default":false},"onMissing":{"type":"string","enum":["null","omit","empty"],"default":"null"}},"required":["source","sourcePath","targetPath"],"additionalProperties":false},"maxItems":200}},"required":["rules"],"additionalProperties":false},"version":{"type":"integer"},"createdBy":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","draft","version","createdBy","updatedAt"]}},"example":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example enhanced_status_profiles_api","draft":{"rules":[{"source":"canonical","sourcePath":"example-sourcepath","targetPath":"example-targetpath","scope":"claim","constantValue":"example-constantvalue","payerId":"87726","type":"string","transform":"none","required":false,"onMissing":"null"}],"layout":"nested","includeClaimSummary":true},"version":1,"createdBy":"example-createdby","updatedAt":"2026-06-08T10:15:30Z"}]}}},"400":{"description":"INVALID_REQUEST: invalid body, query, or invalid supplied Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}}}},"401":{"description":"AUTHENTICATION_REQUIRED: bearer key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}}}},"403":{"description":"ACCESS_DENIED: insufficient scope or access","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}}}},"404":{"description":"NOT_FOUND: resource not found within this organization","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}}}},"409":{"description":"REQUEST_CONFLICT: idempotency, mapping, or processing conflict","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}}}},"422":{"description":"REQUEST_UNPROCESSABLE: missing inputs or unpublished profile","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}}}},"429":{"description":"RATE_LIMITED: retry later","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}}}},"500":{"description":"INTERNAL_ERROR: sanitized server error; retry submission with the same Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}}}}}},"post":{"operationId":"saveEnhancedStatusProfileApi","summary":"Save mapping draft","description":"Requires claim-status:mappings scope. ","tags":["Enhanced claim status"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"definition":{"type":"object","properties":{"layout":{"type":"string","enum":["nested","flat_rows"],"default":"nested"},"includeClaimSummary":{"type":"boolean","default":true},"rules":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["canonical","search","valueAdds","context","constant"]},"scope":{"type":"string","enum":["claim","serviceLine"],"default":"claim"},"sourcePath":{"type":"string","maxLength":256,"pattern":"^\\$(?:\\.[A-Za-z_][A-Za-z0-9_]*|\\[\\d+\\])*$"},"targetPath":{"type":"string","maxLength":256,"pattern":"^[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)*$"},"constantValue":{"anyOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}]},"payerId":{"type":"string","maxLength":64},"type":{"type":"string","enum":["string","decimal_string","boolean","json"],"default":"string"},"transform":{"type":"string","enum":["none","trim","uppercase","lowercase","date_ddmmyyyy","currency_usd","modifier_codes","modifier_descriptions"],"default":"none"},"required":{"type":"boolean","default":false},"onMissing":{"type":"string","enum":["null","omit","empty"],"default":"null"}},"required":["source","sourcePath","targetPath"],"additionalProperties":false},"maxItems":200}},"required":["rules"],"additionalProperties":false}},"required":["name","definition"]},"example":{"name":"Example save_enhanced_status_profile_api","definition":{"rules":[{"source":"canonical","sourcePath":"example-sourcepath","targetPath":"example-targetpath","scope":"claim","constantValue":"example-constantvalue","payerId":"87726","type":"string","transform":"none","required":false,"onMissing":"null"}],"layout":"nested","includeClaimSummary":true},"id":"00000000-0000-4000-8000-000000000001"}}}},"responses":{"201":{"description":"Saved editable profile draft.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"draft":{"type":"object","properties":{"layout":{"type":"string","enum":["nested","flat_rows"],"default":"nested"},"includeClaimSummary":{"type":"boolean","default":true},"rules":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["canonical","search","valueAdds","context","constant"]},"scope":{"type":"string","enum":["claim","serviceLine"],"default":"claim"},"sourcePath":{"type":"string","maxLength":256,"pattern":"^\\$(?:\\.[A-Za-z_][A-Za-z0-9_]*|\\[\\d+\\])*$"},"targetPath":{"type":"string","maxLength":256,"pattern":"^[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)*$"},"constantValue":{"anyOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}]},"payerId":{"type":"string","maxLength":64},"type":{"type":"string","enum":["string","decimal_string","boolean","json"],"default":"string"},"transform":{"type":"string","enum":["none","trim","uppercase","lowercase","date_ddmmyyyy","currency_usd","modifier_codes","modifier_descriptions"],"default":"none"},"required":{"type":"boolean","default":false},"onMissing":{"type":"string","enum":["null","omit","empty"],"default":"null"}},"required":["source","sourcePath","targetPath"],"additionalProperties":false},"maxItems":200}},"required":["rules"],"additionalProperties":false},"version":{"type":"integer"},"createdBy":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","draft","version","createdBy","updatedAt"]},"example":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example save_enhanced_status_profile_api","draft":{"rules":[{"source":"canonical","sourcePath":"example-sourcepath","targetPath":"example-targetpath","scope":"claim","constantValue":"example-constantvalue","payerId":"87726","type":"string","transform":"none","required":false,"onMissing":"null"}],"layout":"nested","includeClaimSummary":true},"version":1,"createdBy":"example-createdby","updatedAt":"2026-06-08T10:15:30Z"}}}},"400":{"description":"INVALID_REQUEST: invalid body, query, or invalid supplied Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}}}},"401":{"description":"AUTHENTICATION_REQUIRED: bearer key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}}}},"403":{"description":"ACCESS_DENIED: insufficient scope or access","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}}}},"404":{"description":"NOT_FOUND: resource not found within this organization","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}}}},"409":{"description":"REQUEST_CONFLICT: idempotency, mapping, or processing conflict","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}}}},"422":{"description":"REQUEST_UNPROCESSABLE: missing inputs or unpublished profile","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}}}},"429":{"description":"RATE_LIMITED: retry later","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}}}},"500":{"description":"INTERNAL_ERROR: sanitized server error; retry submission with the same Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}}}}}}},"/api/v1/claim-status/profiles/{id}/publish":{"post":{"operationId":"publishEnhancedStatusProfileApi","summary":"Publish immutable mapping version","description":"Requires claim-status:mappings scope. ","tags":["Enhanced claim status"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Updated profile; version is the published version number. Pass id as mappingProfileId when creating an inquiry.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"draft":{"type":"object","properties":{"layout":{"type":"string","enum":["nested","flat_rows"],"default":"nested"},"includeClaimSummary":{"type":"boolean","default":true},"rules":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["canonical","search","valueAdds","context","constant"]},"scope":{"type":"string","enum":["claim","serviceLine"],"default":"claim"},"sourcePath":{"type":"string","maxLength":256,"pattern":"^\\$(?:\\.[A-Za-z_][A-Za-z0-9_]*|\\[\\d+\\])*$"},"targetPath":{"type":"string","maxLength":256,"pattern":"^[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)*$"},"constantValue":{"anyOf":[{"type":"string","maxLength":1000},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}]},"payerId":{"type":"string","maxLength":64},"type":{"type":"string","enum":["string","decimal_string","boolean","json"],"default":"string"},"transform":{"type":"string","enum":["none","trim","uppercase","lowercase","date_ddmmyyyy","currency_usd","modifier_codes","modifier_descriptions"],"default":"none"},"required":{"type":"boolean","default":false},"onMissing":{"type":"string","enum":["null","omit","empty"],"default":"null"}},"required":["source","sourcePath","targetPath"],"additionalProperties":false},"maxItems":200}},"required":["rules"],"additionalProperties":false},"version":{"type":"integer"},"createdBy":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","draft","version","createdBy","updatedAt"]},"example":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example publish_enhanced_status_profile_api","draft":{"rules":[{"source":"canonical","sourcePath":"example-sourcepath","targetPath":"example-targetpath","scope":"claim","constantValue":"example-constantvalue","payerId":"87726","type":"string","transform":"none","required":false,"onMissing":"null"}],"layout":"nested","includeClaimSummary":true},"version":1,"createdBy":"example-createdby","updatedAt":"2026-06-08T10:15:30Z"}}}},"400":{"description":"INVALID_REQUEST: invalid body, query, or invalid supplied Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"INVALID_REQUEST","message":"invalid body, query, or invalid supplied Idempotency-Key","source":"api","retryable":false}]}}}},"401":{"description":"AUTHENTICATION_REQUIRED: bearer key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"AUTHENTICATION_REQUIRED","message":"bearer key missing or invalid","source":"api","retryable":false}]}}}},"403":{"description":"ACCESS_DENIED: insufficient scope or access","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"ACCESS_DENIED","message":"insufficient scope or access","source":"api","retryable":false}]}}}},"404":{"description":"NOT_FOUND: resource not found within this organization","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"NOT_FOUND","message":"resource not found within this organization","source":"api","retryable":false}]}}}},"409":{"description":"REQUEST_CONFLICT: idempotency, mapping, or processing conflict","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_CONFLICT","message":"idempotency, mapping, or processing conflict","source":"api","retryable":false}]}}}},"422":{"description":"REQUEST_UNPROCESSABLE: missing inputs or unpublished profile","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}},"example":{"ok":false,"errors":[{"code":"REQUEST_UNPROCESSABLE","message":"missing inputs or unpublished profile","source":"api","retryable":false}]}}}},"429":{"description":"RATE_LIMITED: retry later","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"RATE_LIMITED","message":"retry later","source":"api","retryable":true}]}}}},"500":{"description":"INTERNAL_ERROR: sanitized server error; retry submission with the same Idempotency-Key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"source":{"type":"string","description":"api, validation, payer, enrichment, processing, normalization, or mapping"},"stage":{"type":"string"},"claimIndex":{"type":"integer"},"httpStatus":{"type":"integer"},"path":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","source","retryable"]}}},"required":["ok","errors"],"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}},"example":{"ok":false,"errors":[{"code":"INTERNAL_ERROR","message":"sanitized server error; retry submission with the same Idempotency-Key","source":"api","retryable":true}]}}}}}}},"/api/v1/eob2era/conversions":{"get":{"operationId":"listEob2EraConversions","summary":"List EOB to ERA conversions","description":"Lists sanitized Explanation of Benefits (EOB) to Electronic Remittance Advice (ERA) conversion records owned by the organization selected by the bearer API key.\n\n### When to use\nUse this endpoint to build conversion worklists, audit public API-created local records, monitor safe processing statuses, or find a conversion before reading detail, updating status, triggering a safe processing transition, or classifying ERA summary fields.\n\n### Before calling\nAuthenticate with an API key that has `eob2era:read` or `eob2era:write`. Choose bounded pagination and the narrowest filters available for status, payer name, check number, ERA status, created-at range, and sort order.\n\n### Request guidance\n`skip` defaults to 0 and is capped at 10000. `take` defaults to 25 and is capped at 100. `payerName` and `checkNumber` are case-insensitive contains filters, while `eraStatus` is an exact string filter. `createdFrom` and `createdTo` are parsed as dates; YYYY-MM-DD bounds are treated as start-of-day and end-of-day UTC respectively.\n\n### Request notes\n- Do not send `organizationId`; the API key selects the tenant.\n- `status` must be one of PENDING, UPLOADED, PROCESSING, COMPLETED, PASSED, REQUIRED_CORRECTION, HUMAN_IN_LOOP, FAILED, or INVALID.\n- `sortBy` accepts createdAt, receivedDate, status, payerName, checkNumber, or totalAmount; `sortOrder` defaults to desc.\n\n### Response semantics\nHTTP 200 returns `data.conversions`, `total`, `skip`, `take`, and `meta.organizationId`. Each conversion is a sanitized local record with status, payer/check summary, monetary string, optional job id, optional ERA status, dates, and booleans indicating whether input and output files exist.\n\n### Response notes\n- The response is local QuickRCM conversion state, not proof that optical character recognition (OCR), large language model (LLM) extraction, or ERA posting occurred.\n- `hasInputFile` and `hasOutputFile` are booleans only; file names, Amazon Simple Storage Service (S3) keys, signed URLs, and raw content are intentionally omitted.\n- `totalAmount` is a decimal string or null.\n- `organizationId` appears in conversion rows and `meta` as authenticated tenant ownership context; it is not a request-time tenant selector.\n\n### Errors and retries\nTreat 400 as malformed filters or invalid dates, 401 as missing or invalid credentials, 403 as insufficient scope or tenant authorization failure, and 429 as a backoff signal. Retry transient 5xx responses with the same filters and pagination.\n\n### Error notes\n- 400 can indicate invalid enum values, pagination bounds, sort fields, or date parsing.\n- 403 means the API key does not have the required EOB to ERA scope or tenant access.\n- 429 should be retried with backoff rather than tight polling.\n","tags":["EOB to ERA"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"skip","in":"query","description":"Zero-based number of conversion records to skip. Defaults to 0 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"take","in":"query","description":"Maximum number of conversion records to return. Defaults to 25 and cannot exceed 100."},{"schema":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"]},"required":false,"name":"status","in":"query","description":"Optional local EOB conversion job status filter."},{"schema":{"type":"string","minLength":1,"maxLength":160},"required":false,"name":"payerName","in":"query","description":"Optional case-insensitive payer-name contains filter. Avoid logging raw payer or patient-adjacent search values."},{"schema":{"type":"string","minLength":1,"maxLength":120},"required":false,"name":"checkNumber","in":"query","description":"Optional case-insensitive payment check number contains filter."},{"schema":{"type":"string","minLength":1,"maxLength":80},"required":false,"name":"eraStatus","in":"query","description":"Optional exact ERA classification status filter."},{"schema":{"type":"string","minLength":1,"description":"Optional inclusive created-at lower bound accepted by Date parsing."},"required":false,"description":"Inclusive created-at lower bound. A YYYY-MM-DD value is interpreted as midnight UTC at the start of that day.","name":"createdFrom","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Optional inclusive created-at upper bound accepted by Date parsing."},"required":false,"description":"Inclusive created-at upper bound. A YYYY-MM-DD value is interpreted as the end of that UTC day.","name":"createdTo","in":"query"},{"schema":{"type":"string","enum":["createdAt","receivedDate","status","payerName","checkNumber","totalAmount"],"default":"createdAt"},"required":false,"name":"sortBy","in":"query","description":"Sort field for the list response: createdAt, receivedDate, status, payerName, checkNumber, or totalAmount."},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"sortOrder","in":"query","description":"Sort direction for the list response: asc or desc."}],"responses":{"200":{"description":"EOB to ERA conversion records for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"]},"payerName":{"type":["string","null"]},"checkNumber":{"type":["string","null"]},"totalAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"},"jobId":{"type":["string","null"]},"eraStatus":{"type":["string","null"]},"receivedDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"hasInputFile":{"type":"boolean"},"hasOutputFile":{"type":"boolean"}},"required":["id","organizationId","status","payerName","checkNumber","totalAmount","jobId","eraStatus","receivedDate","createdAt","hasInputFile","hasOutputFile"],"example":{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true}}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["conversions","total","skip","take"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"conversions":[{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true}],"total":1,"skip":1,"take":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createEob2EraConversion","summary":"Create EOB to ERA conversion","description":"Validates an Explanation of Benefits (EOB) upload request or creates a local EOB-to-ERA conversion record from an existing organization-owned File row.\n\n### When to use\nUse validate-only mode while integrating file metadata, or use local-record mode after the EOB file already exists in QuickRCM and you need a conversion tracking record.\n\n### Before calling\nAuthenticate with `eob2era:write`. Know the file name, MIME type, and size. For record creation, resolve `inputFileId` from an existing File in the same organization; this endpoint does not create the file or upload target.\n\n### Request guidance\n`fileName`, `fileType`, and `fileSize` are required. Supported MIME types are application/pdf, image/tiff, image/png, and image/jpeg. `fileSize` is capped at 50 MiB. When `validateOnly` is true, no File lookup or record creation occurs. When `validateOnly` is false or omitted, `inputFileId` is required and must belong to the authenticated organization. If `payerName` is omitted while creating a local record, the handler stores the literal value `Unknown` rather than null.\n\n### Request notes\n- `inputFileId` is required unless `validateOnly` is true.\n- This endpoint never creates Amazon Simple Storage Service (S3) presigned upload URLs.\n- Use file names that avoid Protected Health Information (PHI) in examples and logs.\n- When `validateOnly` is false and `payerName` is omitted, the created local conversion uses `payerName: \"Unknown\"`.\n\n### Response semantics\nHTTP 200 means the request shape was validated with mode VALIDATE_ONLY, null conversion, and side effects marked not_performed. HTTP 201 means a local EobConversionJob record was created with mode LOCAL_RECORD_ONLY, status UPLOADED, and side effects still marked not_performed.\n\n### Response notes\n- `sideEffects.s3`, `sideEffects.sqs`, and `sideEffects.ocrLlm` are always `not_performed` in the public response schema.\n- A 201 response creates local tracking only; it does not run optical character recognition (OCR), large language model (LLM) extraction, ERA generation, or payment posting.\n- The created public conversion response uses sanitized conversion fields.\n\n### Errors and retries\nFix 400 validation failures before retrying. A 404 means the supplied input file was not found in the authenticated organization. After a timeout in local-record mode, list conversions or search by your own workflow context before retrying because no idempotency key is declared.\n\n### Error notes\n- 400 can mean `inputFileId` was omitted when validateOnly was false.\n- 404 means the existing File id did not resolve inside the API key organization.\n- 403 means the API key lacks `eob2era:write`.\n","tags":["EOB to ERA"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Required display file name for the Explanation of Benefits (EOB) input. Keep it free of Protected Health Information (PHI) and do not include storage paths or signed URLs."},"fileType":{"type":"string","enum":["application/pdf","image/tiff","image/png","image/jpeg"],"description":"Required MIME type. Supported values are application/pdf, image/tiff, image/png, and image/jpeg."},"fileSize":{"type":"integer","minimum":1,"maximum":52428800,"description":"Required file size in bytes. The public schema accepts 1 through 52428800 bytes."},"inputFileId":{"type":"string","minLength":1,"description":"Existing QuickRCM File identifier in the authenticated organization. Required unless validateOnly is true."},"payerName":{"type":"string","minLength":1,"maxLength":160,"description":"Optional payer display name stored on the local conversion record. If omitted during non-validate creation, QuickRCM stores the literal value `Unknown`."},"checkNumber":{"type":"string","minLength":1,"maxLength":120,"description":"Optional payment check number or remittance reference for reconciliation."},"receivedDate":{"type":"string","minLength":1,"description":"Optional received date for the EOB. YYYY-MM-DD is accepted and stored at UTC midnight."},"validateOnly":{"type":"boolean","default":false,"description":"When true, validates the request and performs no File lookup, DB creation, Amazon Simple Storage Service (S3) work, Amazon Simple Queue Service (SQS) work, optical character recognition (OCR), or large language model (LLM) processing."}},"required":["fileName","fileType","fileSize"],"example":{"fileName":"safe-eob.pdf","fileType":"application/pdf","fileSize":1048576,"payerName":"Example Payer","receivedDate":"2026-06-08","validateOnly":true}},"example":{"fileName":"safe-eob.pdf","fileType":"application/pdf","fileSize":1048576,"payerName":"Example Payer","receivedDate":"2026-06-08","validateOnly":true}}},"description":"`fileName`, `fileType`, and `fileSize` are required. Supported MIME types are application/pdf, image/tiff, image/png, and image/jpeg. `fileSize` is capped at 50 MiB. When `validateOnly` is true, no File lookup or record creation occurs. When `validateOnly` is false or omitted, `inputFileId` is required and must belong to the authenticated organization. If `payerName` is omitted while creating a local record, the handler stores the literal value `Unknown` rather than null."},"responses":{"200":{"description":"The upload request is valid and no side effects were performed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["VALIDATE_ONLY","LOCAL_RECORD_ONLY"]},"validated":{"type":"boolean"},"conversion":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"]},"payerName":{"type":["string","null"]},"checkNumber":{"type":["string","null"]},"totalAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"},"jobId":{"type":["string","null"]},"eraStatus":{"type":["string","null"]},"receivedDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"hasInputFile":{"type":"boolean"},"hasOutputFile":{"type":"boolean"}},"required":["id","organizationId","status","payerName","checkNumber","totalAmount","jobId","eraStatus","receivedDate","createdAt","hasInputFile","hasOutputFile"],"example":{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true}},"sideEffects":{"type":"object","properties":{"s3":{"type":"string","enum":["not_performed"]},"sqs":{"type":"string","enum":["not_performed"]},"ocrLlm":{"type":"string","enum":["not_performed"]}},"required":["s3","sqs","ocrLlm"]}},"required":["mode","validated","conversion","sideEffects"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"],"example":{"success":true,"data":{"mode":"VALIDATE_ONLY","validated":true,"conversion":null,"sideEffects":{"s3":"not_performed","sqs":"not_performed","ocrLlm":"not_performed"}},"meta":{"organizationId":"org_example_1"}}},"example":{"success":true,"data":{"mode":"VALIDATE_ONLY","validated":true,"conversion":null,"sideEffects":{"s3":"not_performed","sqs":"not_performed","ocrLlm":"not_performed"}},"meta":{"organizationId":"org_example_1"}}}}},"201":{"description":"A DB-only EOB conversion record was created for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["VALIDATE_ONLY","LOCAL_RECORD_ONLY"]},"validated":{"type":"boolean"},"conversion":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"]},"payerName":{"type":["string","null"]},"checkNumber":{"type":["string","null"]},"totalAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"},"jobId":{"type":["string","null"]},"eraStatus":{"type":["string","null"]},"receivedDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"hasInputFile":{"type":"boolean"},"hasOutputFile":{"type":"boolean"}},"required":["id","organizationId","status","payerName","checkNumber","totalAmount","jobId","eraStatus","receivedDate","createdAt","hasInputFile","hasOutputFile"],"example":{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true}},"sideEffects":{"type":"object","properties":{"s3":{"type":"string","enum":["not_performed"]},"sqs":{"type":"string","enum":["not_performed"]},"ocrLlm":{"type":"string","enum":["not_performed"]}},"required":["s3","sqs","ocrLlm"]}},"required":["mode","validated","conversion","sideEffects"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"],"example":{"success":true,"data":{"mode":"LOCAL_RECORD_ONLY","validated":true,"conversion":{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true},"sideEffects":{"s3":"not_performed","sqs":"not_performed","ocrLlm":"not_performed"}},"meta":{"organizationId":"org_example_1"}}},"example":{"success":true,"data":{"mode":"LOCAL_RECORD_ONLY","validated":true,"conversion":{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true},"sideEffects":{"s3":"not_performed","sqs":"not_performed","ocrLlm":"not_performed"}},"meta":{"organizationId":"org_example_1"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Input File not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/eob2era/conversions/{conversionId}":{"get":{"operationId":"getEob2EraConversion","summary":"Get EOB to ERA conversion","description":"Returns one sanitized Explanation of Benefits (EOB) to Electronic Remittance Advice (ERA) conversion record when it belongs to the authenticated organization.\n\n### When to use\nUse this after listEob2EraConversions, createEob2EraConversion, a safe processing transition, a bulk update result, or an internal workflow gives you a trusted conversion id.\n\n### Before calling\nAuthenticate with `eob2era:read` or `eob2era:write`. Use a `conversionId` obtained from the same tenant context; wrong-organization identifiers should be treated as not found.\n\n### Request guidance\nPass `conversionId` in the path. This endpoint has no request body and no public organization selector.\n\n### Request notes\n- `conversionId` is path-only.\n- Do not guess conversion identifiers across tenants.\n- No request body is declared.\n\n### Response semantics\nHTTP 200 returns one sanitized local conversion in `data.conversion` plus `meta.organizationId`. The response intentionally exposes file-presence booleans rather than file keys, file names, signed URLs, operator notes, raw parser fields, or raw payer payloads.\n\n### Response notes\n- Returned fields are safe public conversion metadata.\n- File storage details and raw conversion artifacts are not returned.\n- Use processEob2EraConversion or classifyEob2EraConversion for safe workflow actions.\n- `organizationId` in the response identifies the authenticated tenant context for the returned conversion and should not be used as a cross-tenant selector.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization conversion context unless a prior trusted response proves the record should exist. Retry only transient 5xx and 429 responses with normal backoff.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant resources.\n- 401 and 403 require credential, scope, or tenant correction.\n","tags":["EOB to ERA"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"conversionId","in":"path","description":"QuickRCM EOB to ERA conversion identifier from the path. It must resolve inside the organization selected by the bearer API key."}],"responses":{"200":{"description":"EOB to ERA conversion for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversion":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"]},"payerName":{"type":["string","null"]},"checkNumber":{"type":["string","null"]},"totalAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"},"jobId":{"type":["string","null"]},"eraStatus":{"type":["string","null"]},"receivedDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"hasInputFile":{"type":"boolean"},"hasOutputFile":{"type":"boolean"}},"required":["id","organizationId","status","payerName","checkNumber","totalAmount","jobId","eraStatus","receivedDate","createdAt","hasInputFile","hasOutputFile"],"example":{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true}}},"required":["conversion"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"conversion":{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"EOB to ERA conversion not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"updateEob2EraConversion","summary":"Update EOB to ERA conversion","description":"Updates safe public fields on one organization-owned Explanation of Benefits (EOB) to Electronic Remittance Advice (ERA) conversion.\n\n### When to use\nUse this when a conversion needs a public workflow status correction, an output File reference adjustment, or a sanitized local note update.\n\n### Before calling\nAuthenticate with `eob2era:write`, read or otherwise trust the current conversion id, and resolve any non-null `outputFileId` from an existing File in the same organization.\n\n### Request guidance\nUse PUT because the public route is declared as PUT, not PATCH. Send at least one of `status`, `outputFileId`, or `note`. `outputFileId` may be null to clear the reference; a non-null value must pass an organization-scoped File lookup. Notes should contain sanitized workflow context only and are not included in the public conversion response.\n\n### Request notes\n- `status` must be a public EOB conversion job status value.\n- `outputFileId: null` clears the output-file reference.\n- A non-null `outputFileId` must identify a File in the same authenticated organization.\n\n### Response semantics\nHTTP 200 returns the updated sanitized conversion. It can reflect status and file-presence changes, but it does not expose the stored note, output file name, Amazon Simple Storage Service (S3) key, generated ERA content, or signed URL.\n\n### Response notes\n- The response contains `hasOutputFile`, not output file storage details.\n- `note` can be written but is not part of the public sanitized conversion schema.\n- This endpoint does not generate or upload ERA files.\n\n### Errors and retries\nTreat 400 as invalid body shape or no update fields, 404 as missing conversion or missing same-tenant output file, and 429 as a backoff signal. After a timeout, re-read the conversion before retrying to avoid stale updates.\n\n### Error notes\n- 400 can mean the body contained no editable fields.\n- 404 can mean either the conversion or non-null output File was not found for the tenant.\n- Do not treat a successful update as payment posting or payer adjudication.\n","tags":["EOB to ERA"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"conversionId","in":"path","description":"QuickRCM EOB to ERA conversion identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"],"description":"Optional target local conversion job status."},"outputFileId":{"type":["string","null"],"minLength":1,"description":"Optional QuickRCM File identifier for an output artifact. Use null to clear it; non-null values must belong to the authenticated organization."},"note":{"type":["string","null"],"maxLength":2000,"description":"Optional sanitized note capped at 2000 characters. It is stored locally but omitted from the sanitized public conversion response."}}},"example":{"status":"PENDING","outputFileId":"00000000-0000-4000-8000-000000000001","note":"Example eob2_era_conversion note"}}},"description":"Use PUT because the public route is declared as PUT, not PATCH. Send at least one of `status`, `outputFileId`, or `note`. `outputFileId` may be null to clear the reference; a non-null value must pass an organization-scoped File lookup. Notes should contain sanitized workflow context only and are not included in the public conversion response."},"responses":{"200":{"description":"Updated conversion for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"conversion":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"]},"payerName":{"type":["string","null"]},"checkNumber":{"type":["string","null"]},"totalAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"},"jobId":{"type":["string","null"]},"eraStatus":{"type":["string","null"]},"receivedDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"hasInputFile":{"type":"boolean"},"hasOutputFile":{"type":"boolean"}},"required":["id","organizationId","status","payerName","checkNumber","totalAmount","jobId","eraStatus","receivedDate","createdAt","hasInputFile","hasOutputFile"],"example":{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true}}},"required":["conversion"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"conversion":{"id":"eob_job_example_1","organizationId":"org_example_1","status":"PASSED","payerName":"Example Payer","checkNumber":"CHK-1000","totalAmount":"125.50","jobId":"job_example_1","eraStatus":"PAID_IN_FULL","receivedDate":"2026-06-08T00:00:00Z","createdAt":"2026-06-08T10:15:30Z","hasInputFile":true,"hasOutputFile":true}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"EOB to ERA conversion or output File not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/eob2era/conversions/{conversionId}/process":{"post":{"operationId":"processEob2EraConversion","summary":"Trigger EOB processing safely","description":"Simulates processing or records a safe local PROCESSING status transition for one organization-owned Explanation of Benefits (EOB) to Electronic Remittance Advice (ERA) conversion.\n\n### When to use\nUse dry-run mode to verify that a conversion exists and that the request is shaped correctly. Use queue-only mode when a public integration should mark the local conversion as ready for processing without invoking the actual processing pipeline.\n\n### Before calling\nAuthenticate with `eob2era:write` and resolve `conversionId` from the same tenant. Decide whether this is a no-write simulation (`dryRun: true`) or a safe local DB status update (`queueOnly: true`).\n\n### Request guidance\nSend `dryRun: true` for simulation or `queueOnly: true` for a safe local update. If both are false or omitted, the handler rejects the request. `priority` accepts low, normal, or high and is echoed in the response, but the public endpoint does not send an Amazon Simple Queue Service (SQS) message.\n\n### Request notes\n- `dryRun` defaults to false for this endpoint.\n- `queueOnly` defaults to false and is required for the DB update path.\n- `queued: true` in the response means safe local status recording, not an Amazon Simple Queue Service (SQS) enqueue.\n\n### Response semantics\nHTTP 202 with mode SIMULATED_ONLY means no database update occurred. HTTP 202 with mode SAFE_WRITE_DB_ONLY means the conversion status was updated to PROCESSING through an organization-scoped update. In both cases, Amazon Simple Queue Service (SQS), optical character recognition (OCR), large language model (LLM), and Amazon Simple Storage Service (S3) side effects are not performed.\n\n### Response notes\n- SIMULATED_ONLY returns status PROCESSING_NOT_STARTED and `queued: false`.\n- SAFE_WRITE_DB_ONLY returns status PROCESSING and `queued: true` after the local update.\n- The response is workflow metadata, not conversion completion.\n\n### Errors and retries\nTreat 400 as missing safe-mode controls, 404 as missing or wrong-organization conversion context, and 429 as a backoff signal. After a timeout in queue-only mode, read the conversion before retrying to avoid repeated status transitions.\n\n### Error notes\n- 400 means neither dryRun nor queueOnly enabled an allowed safe path.\n- 404 can intentionally hide wrong-tenant conversions.\n- Do not retry 202 responses as if they were live processing acknowledgements.\n","tags":["EOB to ERA"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"conversionId","in":"path","description":"QuickRCM EOB to ERA conversion identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":false,"description":"When true, performs only a safe local database status transition; no Amazon Simple Queue Service (SQS) message is sent."},"dryRun":{"type":"boolean","default":false,"description":"When true, simulates the processing trigger without changing the database."},"priority":{"type":"string","enum":["low","normal","high"],"default":"normal","description":"Requested processing priority label. Valid values are low, normal, and high; the current public handler echoes it without queueing external work."}},"example":{"dryRun":true,"priority":"normal"}},"example":{"dryRun":true,"priority":"normal"}}},"description":"Send `dryRun: true` for simulation or `queueOnly: true` for a safe local update. If both are false or omitted, the handler rejects the request. `priority` accepts low, normal, or high and is echoed in the response, but the public endpoint does not send an Amazon Simple Queue Service (SQS) message."},"responses":{"202":{"description":"Processing was simulated or recorded without external side effects.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY","SAFE_WRITE_DB_ONLY"]},"conversionId":{"type":"string"},"queued":{"type":"boolean"},"simulated":{"type":"boolean"},"priority":{"type":"string","enum":["low","normal","high"]},"status":{"type":"string"}},"required":["mode","conversionId","queued","simulated","priority","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"],"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","conversionId":"eob_job_example_1","queued":false,"simulated":true,"priority":"normal","status":"PROCESSING_NOT_STARTED"},"meta":{"organizationId":"org_example_1"}}},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","conversionId":"eob_job_example_1","queued":false,"simulated":true,"priority":"normal","status":"PROCESSING_NOT_STARTED"},"meta":{"organizationId":"org_example_1"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"EOB to ERA conversion not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/eob2era/conversions/bulk":{"put":{"operationId":"bulkUpdateEob2EraConversions","summary":"Bulk update EOB to ERA conversions","description":"Bulk-updates safe public fields on Explanation of Benefits (EOB) to Electronic Remittance Advice (ERA) conversion records whose IDs belong to the authenticated organization.\n\n### When to use\nUse this for internal review workflows that need to move multiple local conversion records to a shared status or apply a sanitized operator note.\n\n### Before calling\nAuthenticate with `eob2era:write`. Collect up to 500 conversion IDs from the same tenant and decide whether to update `status`, `note`, or both.\n\n### Request guidance\n`ids` is required and accepts 1 through 500 identifiers. Send at least one editable field: `status` and/or `note`. Keep notes short, sanitized, and free of Protected Health Information (PHI), raw Electronic Data Interchange (EDI), Amazon Simple Storage Service (S3) keys, credentials, transcripts, and raw payer payloads.\n\n### Request notes\n- `ids` must contain at least one and at most 500 conversion identifiers.\n- `status` must be one of the EOB conversion job status enum values when supplied.\n- No output file links, processing side effects, or classification changes are performed by this endpoint.\n\n### Response semantics\nHTTP 200 returns mode SAFE_WRITE_DB_ONLY, `requested`, and `updated`. The handler uses an organization-scoped updateMany; `updated` can be lower than `requested` when IDs are missing, already filtered out by tenant scope, or otherwise not updated.\n\n### Response notes\n- `requested` is the number of ids supplied.\n- `updated` is the number of organization-owned records affected by the update.\n- The response does not list per-id success or failure details.\n\n### Errors and retries\nFix empty id arrays, too-large batches, invalid statuses, or missing update fields after a 400. After a timeout, list or read affected conversions before retrying to avoid duplicate note/status writes.\n\n### Error notes\n- 400 can mean no editable fields were supplied.\n- 403 means the caller lacks write access.\n- This endpoint does not declare a 404 for individual missing IDs; use the updated count and follow-up reads.\n","tags":["EOB to ERA"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":500,"description":"Array of EOB to ERA conversion identifiers to update. The update remains scoped to the API key organization."},"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"],"description":"Optional target local EOB conversion job status."},"note":{"type":["string","null"],"maxLength":2000,"description":"Optional sanitized operator note. The note can be updated but is not exposed in sanitized conversion responses."}},"required":["ids"]},"example":{"ids":["example-ids"],"status":"PENDING","note":"Example update_eob2_era_conversion note"}}},"description":"`ids` is required and accepts 1 through 500 identifiers. Send at least one editable field: `status` and/or `note`. Keep notes short, sanitized, and free of Protected Health Information (PHI), raw Electronic Data Interchange (EDI), Amazon Simple Storage Service (S3) keys, credentials, transcripts, and raw payer payloads."},"responses":{"200":{"description":"Bulk update result for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]},"requested":{"type":"integer","minimum":1},"updated":{"type":"integer","minimum":0}},"required":["mode","requested","updated"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SAFE_WRITE_DB_ONLY","requested":1,"updated":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/eob2era/conversions/{conversionId}/classify":{"post":{"operationId":"classifyEob2EraConversion","summary":"Classify EOB to ERA conversion","description":"Classifies caller-supplied safe Electronic Remittance Advice (ERA) summary fields for one organization-owned Explanation of Benefits (EOB) to ERA conversion and optionally persists only the resulting ERA status.\n\n### When to use\nUse this when an integration already has a sanitized remittance summary and wants QuickRCM's local ERA classification labels without submitting raw X12 835 Electronic Remittance Advice transaction content or invoking EOB extraction.\n\n### Before calling\nAuthenticate with `eob2era:write`, resolve `conversionId` from the same tenant, and build a strict `payload` using only the documented financial, adjustment, CARC, and capitation summary fields.\n\n### Request guidance\n`payload` is required and rejects unknown properties. `dryRun` defaults to true, returning a classification without writing. Set `dryRun: false` only when you want the resulting `eraStatus` persisted to the conversion. Do not send raw X12 835 Electronic Remittance Advice transaction payloads, optical character recognition (OCR) text, payer payloads, Amazon Simple Storage Service (S3) keys, vendor responses, transcripts, or denial creation instructions.\n\n### Request notes\n- `payload.adjustments` is capped at 100 entries; each adjustment allows only groupCode, reasonCode, and amount.\n- `carcCodes` is capped at 100 Claim Adjustment Reason Code (CARC) strings.\n- The classifier can return PAID_IN_FULL, PARTIALLY_PAID, DENIED_ZERO_PAYMENT, CAPITATED_PAYMENT, ADJUSTED_CLAIM, OVERPAYMENT, UNDERPAYMENT, or REVIEW_REQUIRED.\n\n### Response semantics\nHTTP 200 returns mode SIMULATED_ONLY with `persisted: false` when dryRun is true, or mode SAFE_WRITE_DB_ONLY with `persisted: true` after an organization-scoped update when dryRun is false. The response includes only the derived `eraStatus` and safe workflow flags.\n\n### Response notes\n- The endpoint does not read Amazon Simple Storage Service (S3), parse a raw X12 835 Electronic Remittance Advice transaction, run optical character recognition (OCR) or large language model (LLM) work, or create denial records.\n- Missing or zero financial summary inputs can classify as REVIEW_REQUIRED.\n- A zero paid amount with capitation context classifies before zero-payment denial logic.\n\n### Errors and retries\nTreat 400 as invalid or unsafe payload shape, 404 as missing or wrong-organization conversion context, and 429 as a backoff signal. Unknown top-level body fields, unknown payload fields, and unknown adjustment fields should be corrected rather than retried unchanged.\n\n### Error notes\n- 400 should be expected for raw835, ocrText, payerPayload, s3Key, or any other undocumented payload fields.\n- 404 can intentionally hide wrong-tenant conversions.\n- Use dry-run mode before enabling persistence in automated workflows.\n","tags":["EOB to ERA"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"conversionId","in":"path","description":"QuickRCM EOB to ERA conversion identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":true,"description":"Defaults to true for classification. When true, returns the derived ERA status without persisting it."},"payload":{"type":"object","properties":{"paidAmount":{"type":["number","null"],"description":"Amount paid by the payer in the summarized ERA data."},"allowedAmount":{"type":["number","null"],"description":"Allowed amount used by the classifier to compare payment coverage."},"patientResponsibility":{"type":["number","null"],"description":"Patient responsibility amount included in total received for classification."},"billedAmount":{"type":["number","null"],"description":"Billed amount used to identify overpayment and adjusted-claim cases."},"expectedContractAmount":{"type":["number","null"],"description":"Optional expected contracted amount used for underpayment classification."},"adjustments":{"type":"array","items":{"type":"object","properties":{"groupCode":{"type":"string","minLength":1,"maxLength":10,"description":"Adjustment group code such as a contractual or payer-responsibility grouping."},"reasonCode":{"type":"string","minLength":1,"maxLength":20,"description":"Adjustment reason code or CARC-like reason value in the safe summary."},"amount":{"type":["number","null"],"description":"Adjustment amount for a safe adjustment summary entry."}},"additionalProperties":false},"maxItems":100,"description":"Optional array of safe adjustment summaries; maximum 100 entries."},"carcCodes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"maxItems":100,"description":"Optional array of CARC code strings used by classification rules; maximum 100 entries."},"capitationFlag":{"type":"boolean","description":"Optional boolean indicating capitation context. CARC code 24 also indicates capitation context in the classifier."}},"additionalProperties":false,"description":"Strict safe Electronic Remittance Advice (ERA) summary object. Raw X12 835 Electronic Remittance Advice transaction content, optical character recognition (OCR) text, payer payloads, Amazon Simple Storage Service (S3) keys, and unknown fields are not accepted."}},"required":["payload"],"additionalProperties":false,"example":{"dryRun":true,"payload":{"paidAmount":125.5,"allowedAmount":125.5,"patientResponsibility":0,"billedAmount":125.5,"adjustments":[],"carcCodes":[]}}},"example":{"dryRun":true,"payload":{"paidAmount":125.5,"allowedAmount":125.5,"patientResponsibility":0,"billedAmount":125.5,"adjustments":[],"carcCodes":[]}}}},"description":"`payload` is required and rejects unknown properties. `dryRun` defaults to true, returning a classification without writing. Set `dryRun: false` only when you want the resulting `eraStatus` persisted to the conversion. Do not send raw X12 835 Electronic Remittance Advice transaction payloads, optical character recognition (OCR) text, payer payloads, Amazon Simple Storage Service (S3) keys, vendor responses, transcripts, or denial creation instructions."},"responses":{"200":{"description":"Classification result for the supplied safe summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY","SAFE_WRITE_DB_ONLY"]},"conversionId":{"type":"string"},"eraStatus":{"type":"string","enum":["PAID_IN_FULL","PARTIALLY_PAID","DENIED_ZERO_PAYMENT","CAPITATED_PAYMENT","ADJUSTED_CLAIM","OVERPAYMENT","UNDERPAYMENT","REVIEW_REQUIRED"]},"persisted":{"type":"boolean"},"simulated":{"type":"boolean"}},"required":["mode","conversionId","eraStatus","persisted","simulated"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"],"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","conversionId":"eob_job_example_1","eraStatus":"PAID_IN_FULL","persisted":false,"simulated":true},"meta":{"organizationId":"org_example_1"}}},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","conversionId":"eob_job_example_1","eraStatus":"PAID_IN_FULL","persisted":false,"simulated":true},"meta":{"organizationId":"org_example_1"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"EOB to ERA conversion not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/v2/era":{"post":{"operationId":"fetchEra","summary":"Fetch ERA","description":"Attempts to retrieve an ERA for the authenticated organization using `tradingPartnerServiceId` and `transactionId`, returning normalized ERA details on automated success or a manual-operations acknowledgement when automated retrieval cannot complete.\n\n### When to use\nUse this endpoint when an integration already has a payer or trading-partner routing identifier plus the vendor transaction identifier for an ERA retrieval request and wants QuickRCM to retrieve or queue follow-up for that remittance.\n\n### Before calling\nAuthenticate with an API key that has `era:write` scope. Resolve `tradingPartnerServiceId` from the payer or trading-partner context used by QuickRCM routing, and pass the vendor transaction ID exactly as provided by the retrieval workflow. Do not send tenant selectors, raw X12 835 content, payer portal credentials, API keys, OAuth tokens, signed storage URLs, or full vendor payloads.\n\n### Request guidance\n`tradingPartnerServiceId` and `transactionId` are required non-empty strings and are trimmed by the handler. The handler resolves the trading partner to a known payer, then asks the routing service for ERA vendor candidates. This operation can call an external ERA vendor when configured and can write local QuickRCM data because a successful fetch stores or reuses a `Remittance`, while fallback creates a local `Task`.\n\n### Request notes\n- `tradingPartnerServiceId` is a payer or trading-partner routing value, not an organization selector.\n- `transactionId` is the vendor transaction identifier used for ERA retrieval and may also serve as the fallback remittance idempotency key when no check number exists.\n- Do not send raw Electronic Data Interchange (EDI), raw X12 835 files, payer responses, credentials, Protected Health Information (PHI)-heavy notes, or storage keys in this request.\n\n### Response semantics\nHTTP 200 returns a direct ERA detail object, not a `{ success, data }` envelope. The required top-level response keys are `eraId`, `payer`, `payee`, `payment`, `claims`, and `providerAdjustments`. Nested values can still be empty strings, zero amounts, null nullable fields, or empty arrays when normalized vendor data is incomplete. For service-line `chargeAmount` and `paidAmount`, null means the stored normalized value was absent or null; Stedi-origin missing or unparseable raw service-line amount strings are normalized to 0 before public serialization. HTTP 202 returns a direct acknowledgement with `taskId`, API acknowledgement `status` (`QUEUED` or `IN_PROGRESS`), `message`, and `estimatedCompletion`; it means QuickRCM queued manual work, not that a payer accepted, adjudicated, or posted the remittance.\n\n### Response notes\n- The 200 response body is the ERA detail object itself.\n- Claim rows intentionally omit patient name and member ID fields even though internal normalized ERA types can contain them.\n- Required response objects are still present when source data is sparse; individual strings may be empty, amount fields may be zero, nullable fields may be null, and arrays may be empty.\n- The 202 response is a local manual-operations queue acknowledgement, not a remittance retrieval success, remittance posting, payer acceptance, or the internal Task row status.\n- Service-line `chargeAmount` and `paidAmount` are nullable in the public schema and serializer; Stedi-origin missing or unparseable raw service-line amount strings currently arrive at the serializer as 0.\n\n### Errors and retries\nTreat 400 as invalid request shape or unknown payer routing, 401 as missing or invalid authentication, 403 as missing ERA scope or authorization failure, and 429 as a backoff signal. If a 200 response is lost after a timeout, retrying the same transaction may reuse the existing Remittance by check number or by `ERA-${transactionId}` when no check number exists. If a 202 response is lost, re-check local task or remittance state before retrying because manual fallback task creation is not documented as idempotent.\n\n### Error notes\n- 400 can mean a required string is blank or the trading partner cannot be resolved to a known payer.\n- 403 means the API key is missing an accepted ERA scope or is not authorized for the resource.\n- Retry 429 or transient 5xx responses with backoff and state checks to avoid duplicate manual work.\n","tags":["ERA"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tradingPartnerServiceId":{"type":"string","minLength":1,"description":"Required payer or trading-partner service identifier used by QuickRCM to resolve payer routing for ERA retrieval. It is trimmed and must not be blank. It is not a tenant selector."},"transactionId":{"type":"string","minLength":1,"description":"Required vendor transaction identifier for the ERA retrieval request. It is trimmed and can be used as a fallback Remittance lookup key when the retrieved ERA has no check number."}},"required":["tradingPartnerServiceId","transactionId"]},"example":{"tradingPartnerServiceId":"00000000-0000-4000-8000-000000000001","transactionId":"00000000-0000-4000-8000-000000000001"}}},"description":"`tradingPartnerServiceId` and `transactionId` are required non-empty strings and are trimmed by the handler. The handler resolves the trading partner to a known payer, then asks the routing service for ERA vendor candidates. This operation can call an external ERA vendor when configured and can write local QuickRCM data because a successful fetch stores or reuses a `Remittance`, while fallback creates a local `Task`."},"responses":{"200":{"description":"Fetched ERA details for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"eraId":{"type":"string"},"payer":{"type":"object","properties":{"payerId":{"type":"string"},"payerName":{"type":"string"},"address":{"type":["object","null"],"properties":{"address1":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"postalCode":{"type":["string","null"]}},"required":["address1","city","state","postalCode"]}},"required":["payerId","payerName","address"]},"payee":{"type":"object","properties":{"npi":{"type":"string"},"name":{"type":"string"},"tin":{"type":"string"}},"required":["npi","name","tin"]},"payment":{"type":"object","properties":{"checkNumber":{"type":"string"},"checkDate":{"type":"string"},"checkAmount":{"type":"number"},"paymentMethod":{"type":"string"},"eftTraceNumber":{"type":"string"}},"required":["checkNumber","checkDate","checkAmount","paymentMethod","eftTraceNumber"]},"claims":{"type":"array","items":{"type":"object","properties":{"patientControlNumber":{"type":"string"},"payerClaimControlNumber":{"type":"string"},"claimStatus":{"type":"string"},"claimStatusDescription":{"type":["string","null"]},"chargeAmount":{"type":"number"},"paidAmount":{"type":"number"},"patientResponsibility":{"type":"number"},"adjustments":{"type":"array","items":{"type":"object","properties":{"groupCode":{"type":"string"},"groupCodeDescription":{"type":"string"},"reasonCode":{"type":"string"},"reasonCodeDescription":{"type":"string"},"amount":{"type":"number"}},"required":["groupCode","groupCodeDescription","reasonCode","reasonCodeDescription","amount"]}},"serviceLines":{"type":"array","items":{"type":"object","properties":{"procedureCode":{"type":["string","null"]},"serviceDate":{"type":["string","null"]},"chargeAmount":{"type":["number","null"]},"paidAmount":{"type":["number","null"]},"lineNumber":{"type":["integer","null"]}},"required":["procedureCode","serviceDate","chargeAmount","paidAmount","lineNumber"]}},"remarkCodes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":"string"}},"required":["code","description"]}}},"required":["patientControlNumber","payerClaimControlNumber","claimStatus","claimStatusDescription","chargeAmount","paidAmount","patientResponsibility","adjustments","serviceLines","remarkCodes"],"description":"ERA claim summary with patient name and member identifiers omitted."}},"providerAdjustments":{"type":"array","items":{"type":"object","properties":{"adjustmentCode":{"type":"string"},"adjustmentDescription":{"type":"string"},"amount":{"type":"number"},"referenceId":{"type":["string","null"]}},"required":["adjustmentCode","adjustmentDescription","amount","referenceId"]}}},"required":["eraId","payer","payee","payment","claims","providerAdjustments"]},"example":{"eraId":"00000000-0000-4000-8000-000000000001","payer":{"payerId":"87726","payerName":"Example fetch_era","address":{"address1":"example-address1","city":"example-city","state":"example-state","postalCode":"example-postalcode"}},"payee":{"npi":"1234567893","name":"Example fetch_era","tin":"example-tin"},"payment":{"checkNumber":"example-checknumber","checkDate":"2026-06-08","checkAmount":125.5,"paymentMethod":"example-paymentmethod","eftTraceNumber":"example-efttracenumber"},"claims":[{"patientControlNumber":"example-patientcontrolnumber","payerClaimControlNumber":"example-payerclaimcontrolnumber","claimStatus":"example-claimstatus","claimStatusDescription":"Example fetch_era note","chargeAmount":125.5,"paidAmount":125.5,"patientResponsibility":1.25,"adjustments":[{"groupCode":"example-groupcode","groupCodeDescription":"Example fetch_era note","reasonCode":"example-reasoncode","reasonCodeDescription":"Example fetch_era note","amount":125.5}],"serviceLines":[{"procedureCode":"example-procedurecode","serviceDate":"2026-06-08","chargeAmount":125.5,"paidAmount":125.5,"lineNumber":1}],"remarkCodes":[{"code":"ERROR","description":"Example fetch_era note"}]}],"providerAdjustments":[{"adjustmentCode":"example-adjustmentcode","adjustmentDescription":"Example fetch_era note","amount":125.5,"referenceId":"00000000-0000-4000-8000-000000000001"}]}}}},"202":{"description":"ERA retrieval was queued for manual operations.","content":{"application/json":{"schema":{"type":"object","properties":{"taskId":{"type":"string"},"status":{"type":"string","enum":["QUEUED","IN_PROGRESS"]},"message":{"type":"string"},"estimatedCompletion":{"type":"string","format":"date-time"}},"required":["taskId","status","message","estimatedCompletion"]},"example":{"taskId":"00000000-0000-4000-8000-000000000001","status":"QUEUED","message":"Request failed","estimatedCompletion":"2026-06-08T10:15:30Z"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Forbidden. The API key is missing an accepted ERA scope or is not authorized for this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/v2/era/{eraId}":{"get":{"operationId":"getEra","summary":"Get ERA","description":"Returns stored normalized ERA details for one remittance when the `eraId` belongs to the organization selected by the bearer API key and stored detail data is available.\n\n### When to use\nUse this endpoint after `fetchEra` returns an `eraId`, after a manual workflow produces a stored remittance, or when an integration needs to re-read sanitized ERA details already saved in QuickRCM.\n\n### Before calling\nAuthenticate with an API key that has `era:read` or `era:write` scope. Use only an `eraId` obtained from a trusted QuickRCM response in the same tenant context. Do not include `organizationId`, query filters, raw X12 835 content, payer credentials, or full vendor payloads.\n\n### Request guidance\n`eraId` is the only public selector and is required in the path. The query schema is empty. The handler looks up `Remittance.findFirst({ where: { id: eraId, organizationId } })`, so wrong-organization IDs do not return details.\n\n### Request notes\n- `eraId` must come from the same organization context as the bearer API key.\n- No query parameters are documented for this endpoint.\n- Do not use this endpoint to request raw X12 835 files, payer portal payloads, or payment posting side effects.\n\n### Response semantics\nHTTP 200 returns the direct sanitized ERA detail object with the same public response shape as successful `fetchEra`. The required top-level response keys are `eraId`, `payer`, `payee`, `payment`, `claims`, and `providerAdjustments`. Service-line `chargeAmount` and `paidAmount` are nullable when stored normalized values are absent or null; records originally normalized from Stedi may contain 0 for missing or unparseable raw service-line amount strings. The response is read-only access to stored normalized detail data. It does not post payments, create denial records, submit claims, expose raw X12 835 loops, or prove payer-side state beyond what was stored in the remittance.\n\n### Response notes\n- The response body is the ERA detail object itself.\n- Claim rows omit patient names and member identifiers.\n- A 200 response means stored detail data was available for the tenant-scoped remittance.\n- Required response objects are still present when stored normalized data is sparse; individual strings may be empty, amount fields may be zero, nullable fields may be null, and arrays may be empty.\n- Service-line `chargeAmount` and `paidAmount` are nullable for absent or null stored normalized values; Stedi-origin stored details may use 0 where the raw service-line amount string was missing or unparseable.\n\n### Errors and retries\nTreat 404 as either a missing remittance, a wrong-tenant remittance ID, or a remittance without stored ERA detail data. Retry 429 and transient 5xx responses with backoff. Do not retry 401 or 403 without correcting credentials or scopes.\n\n### Error notes\n- 404 can hide wrong-tenant remittance IDs and can also mean stored detail data is unavailable.\n- 403 means the API key is missing an accepted ERA scope or is not authorized for the resource.\n- 429 should be retried with backoff.\n","tags":["ERA"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"eraId","in":"path","description":"QuickRCM remittance identifier in the path and response. The remittance must belong to the organization selected by the bearer API key and must have stored ERA detail data."}],"responses":{"200":{"description":"Stored ERA details for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"eraId":{"type":"string"},"payer":{"type":"object","properties":{"payerId":{"type":"string"},"payerName":{"type":"string"},"address":{"type":["object","null"],"properties":{"address1":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"postalCode":{"type":["string","null"]}},"required":["address1","city","state","postalCode"]}},"required":["payerId","payerName","address"]},"payee":{"type":"object","properties":{"npi":{"type":"string"},"name":{"type":"string"},"tin":{"type":"string"}},"required":["npi","name","tin"]},"payment":{"type":"object","properties":{"checkNumber":{"type":"string"},"checkDate":{"type":"string"},"checkAmount":{"type":"number"},"paymentMethod":{"type":"string"},"eftTraceNumber":{"type":"string"}},"required":["checkNumber","checkDate","checkAmount","paymentMethod","eftTraceNumber"]},"claims":{"type":"array","items":{"type":"object","properties":{"patientControlNumber":{"type":"string"},"payerClaimControlNumber":{"type":"string"},"claimStatus":{"type":"string"},"claimStatusDescription":{"type":["string","null"]},"chargeAmount":{"type":"number"},"paidAmount":{"type":"number"},"patientResponsibility":{"type":"number"},"adjustments":{"type":"array","items":{"type":"object","properties":{"groupCode":{"type":"string"},"groupCodeDescription":{"type":"string"},"reasonCode":{"type":"string"},"reasonCodeDescription":{"type":"string"},"amount":{"type":"number"}},"required":["groupCode","groupCodeDescription","reasonCode","reasonCodeDescription","amount"]}},"serviceLines":{"type":"array","items":{"type":"object","properties":{"procedureCode":{"type":["string","null"]},"serviceDate":{"type":["string","null"]},"chargeAmount":{"type":["number","null"]},"paidAmount":{"type":["number","null"]},"lineNumber":{"type":["integer","null"]}},"required":["procedureCode","serviceDate","chargeAmount","paidAmount","lineNumber"]}},"remarkCodes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":"string"}},"required":["code","description"]}}},"required":["patientControlNumber","payerClaimControlNumber","claimStatus","claimStatusDescription","chargeAmount","paidAmount","patientResponsibility","adjustments","serviceLines","remarkCodes"],"description":"ERA claim summary with patient name and member identifiers omitted."}},"providerAdjustments":{"type":"array","items":{"type":"object","properties":{"adjustmentCode":{"type":"string"},"adjustmentDescription":{"type":"string"},"amount":{"type":"number"},"referenceId":{"type":["string","null"]}},"required":["adjustmentCode","adjustmentDescription","amount","referenceId"]}}},"required":["eraId","payer","payee","payment","claims","providerAdjustments"]},"example":{"eraId":"00000000-0000-4000-8000-000000000001","payer":{"payerId":"87726","payerName":"Example era","address":{"address1":"example-address1","city":"example-city","state":"example-state","postalCode":"example-postalcode"}},"payee":{"npi":"1234567893","name":"Example era","tin":"example-tin"},"payment":{"checkNumber":"example-checknumber","checkDate":"2026-06-08","checkAmount":125.5,"paymentMethod":"example-paymentmethod","eftTraceNumber":"example-efttracenumber"},"claims":[{"patientControlNumber":"example-patientcontrolnumber","payerClaimControlNumber":"example-payerclaimcontrolnumber","claimStatus":"example-claimstatus","claimStatusDescription":"Example era note","chargeAmount":125.5,"paidAmount":125.5,"patientResponsibility":1.25,"adjustments":[{"groupCode":"example-groupcode","groupCodeDescription":"Example era note","reasonCode":"example-reasoncode","reasonCodeDescription":"Example era note","amount":125.5}],"serviceLines":[{"procedureCode":"example-procedurecode","serviceDate":"2026-06-08","chargeAmount":125.5,"paidAmount":125.5,"lineNumber":1}],"remarkCodes":[{"code":"ERROR","description":"Example era note"}]}],"providerAdjustments":[{"adjustmentCode":"example-adjustmentcode","adjustmentDescription":"Example era note","amount":125.5,"referenceId":"00000000-0000-4000-8000-000000000001"}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Forbidden. The API key is missing an accepted ERA scope or is not authorized for this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"ERA not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/gfe/estimates":{"get":{"operationId":"listGoodFaithEstimates","summary":"List Good Faith Estimates","description":"Lists Good Faith Estimate records owned by the organization selected by the bearer API key, with optional filters for local GFE status, patient, service-date range, overdue flag, and page-based pagination.\n\n### When to use\nUse this endpoint to populate GFE worklists, compliance dashboards, overdue delivery reviews, patient-specific estimate history, or integration reconciliation views before opening one estimate in detail.\n\n### Before calling\nAuthenticate with an API key that has `gfe:read` or `gfe:write`. Choose narrow filters such as `status`, `patientId`, `dateFrom`, `dateTo`, and `isOverdue`.\n\n### Request guidance\n`page` and `pageSize` are one-based pagination controls; the operation defaults to page 1 and page size 25 when omitted. The public schema caps `page` at 10000 and `pageSize` at 100. `dateFrom` and `dateTo` accept valid `YYYY-MM-DD` dates or ISO datetimes, and `dateFrom` must be on or before `dateTo`. Do not send `organizationId`; tenant scope comes from the API key.\n\n### Request notes\n- `status` values are `GFE_DRAFT`, `GFE_GENERATED`, `GFE_DELIVERED`, `GFE_ACKNOWLEDGED`, `GFE_DISPUTED`, `GFE_EXPIRED`, and `GFE_VOID`.\n- `isOverdue` is a string query value, either `true` or `false`.\n- Use service-date filters for period reviews instead of exporting all estimates.\n- Date-only filters are accepted as calendar dates and parsed by the public handler before operation filtering; ISO datetimes are also accepted when callers need exact boundaries.\n\n### Response semantics\nThe response returns `data.estimates`, `total`, `page`, `pageSize`, and `meta.organizationId`. Estimate rows use the public estimate shape and include identifiers, local status, provider and facility display fields, line items, monetary strings, delivery timestamps, overdue state, and timestamps. Current list implementation does not include the `idrCase` relation before serialization, so list rows should be documented with `idrCase: null`; use `getGoodFaithEstimate` for linked IDR detail.\n\n### Response notes\n- `data.estimates` is local QuickRCM GFE state, not proof that a delivery channel transmitted a document.\n- Current list rows return `idrCase: null`; retrieve one estimate to see linked IDR case details.\n- Monetary response fields are serialized as strings.\n\n### Errors and retries\nTreat 400 as invalid filters or pagination, 401/403 as credential, scope, or tenant-access issues, and transient server failures as retryable with backoff. Do not retry malformed date ranges unchanged.\n\n### Error notes\n- 400 can indicate invalid enum values, invalid calendar dates, `dateFrom` after `dateTo`, or pagination bounds.\n- 403 means the API key lacks tenant access or the required GFE permission.\n- Do not log broad query parameters if they contain patient-adjacent workflow context.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["GFE_DRAFT","GFE_GENERATED","GFE_DELIVERED","GFE_ACKNOWLEDGED","GFE_DISPUTED","GFE_EXPIRED","GFE_VOID"]},"required":false,"name":"status","in":"query","description":"Optional local Good Faith Estimate lifecycle status filter."},{"schema":{"type":"string","minLength":1},"required":false,"name":"patientId","in":"query","description":"Optional QuickRCM patient identifier. Results remain scoped to the API key organization."},{"schema":{"type":"string","minLength":1},"required":false,"name":"dateFrom","in":"query","description":"Inclusive lower bound for estimate service dates. Use `YYYY-MM-DD` or an ISO datetime string."},{"schema":{"type":"string","minLength":1},"required":false,"name":"dateTo","in":"query","description":"Inclusive upper bound for estimate service dates. It must be on or after `dateFrom` when both are supplied."},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"isOverdue","in":"query","description":"Optional string filter for estimates marked overdue by delivery-deadline logic; accepted values are `true` and `false`."},{"schema":{"type":"integer","minimum":1,"maximum":10000},"required":false,"name":"page","in":"query","description":"One-based page number. Defaults to 1 in the operation layer and is capped at 10000 by the public schema."},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"pageSize","in":"query","description":"Maximum estimates returned per page. Defaults to 25 in the operation layer and is capped at 100 by the public schema."}],"responses":{"200":{"description":"Good Faith Estimate list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"estimates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"estimateNumber":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["GFE_DRAFT","GFE_GENERATED","GFE_DELIVERED","GFE_ACKNOWLEDGED","GFE_DISPUTED","GFE_EXPIRED","GFE_VOID"]},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"facilityName":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"serviceDate":{"type":["string","null"],"format":"date-time"},"lineItems":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"unitCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"providerType":{"type":["string","null"]}},"required":["cptCode","description","quantity","unitCharge","totalCharge","providerName","providerNpi","providerType"]}},"totalEstimatedCost":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"patientResponsibility":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"deliveryMethod":{"type":["string","null"],"enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"]},"deliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryDeadline":{"type":["string","null"],"format":"date-time"},"isDeliveryOverdue":{"type":"boolean"},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"disputedAt":{"type":["string","null"],"format":"date-time"},"idrCase":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"]},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"estimatedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"resolvedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"qualifyingPaymentAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"providerOfferAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payerCounterAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"arbitrationAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"initiatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","status","billedAmount","estimatedAmount","resolvedAmount","qualifyingPaymentAmount","providerOfferAmount","payerCounterAmount","arbitrationAmount","initiatedAt","resolvedAt","createdAt","updatedAt"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","estimateNumber","patientId","appointmentId","status","providerName","providerNpi","facilityName","facilityId","serviceDate","lineItems","totalEstimatedCost","patientResponsibility","deliveryMethod","deliveredAt","deliveryDeadline","isDeliveryOverdue","acknowledgedAt","disputedAt","idrCase","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1}},"required":["estimates","total","page","pageSize"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"estimates":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","estimateNumber":"example-estimatenumber","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"GFE_DRAFT","providerName":"Example good_faith_estimate","providerNpi":"1234567893","facilityName":"Example good_faith_estimate","facilityId":"00000000-0000-4000-8000-000000000001","serviceDate":"2026-06-08T10:15:30Z","lineItems":[{"cptCode":"example-cptcode","description":"Example good_faith_estimate note","quantity":1.25,"unitCharge":"example-unitcharge","totalCharge":"example-totalcharge","providerName":"Example good_faith_estimate","providerNpi":"1234567893","providerType":"example-providertype"}],"totalEstimatedCost":"example-totalestimatedcost","patientResponsibility":"example-patientresponsibility","deliveryMethod":"GFE_DEL_EMAIL","deliveredAt":"2026-06-08T10:15:30Z","deliveryDeadline":"2026-06-08T10:15:30Z","isDeliveryOverdue":true,"acknowledgedAt":"2026-06-08T10:15:30Z","disputedAt":"2026-06-08T10:15:30Z","idrCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"IDR_INITIATED","billedAmount":"example-billedamount","estimatedAmount":"example-estimatedamount","resolvedAmount":"example-resolvedamount","qualifyingPaymentAmount":"example-qualifyingpaymentamount","providerOfferAmount":"example-providerofferamount","payerCounterAmount":"example-payercounteramount","arbitrationAmount":"example-arbitrationamount","initiatedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}},"post":{"operationId":"createGoodFaithEstimate","summary":"Create a Good Faith Estimate","description":"Creates a local Good Faith Estimate for an existing organization-owned patient, computes line totals and total estimated cost, assigns a generated estimate number, calculates a delivery deadline, and attempts PDF generation.\n\n### When to use\nUse this when an integration has the required patient, provider, facility, service-date, and line-item inputs needed to create a GFE record before delivery and patient acknowledgment workflows.\n\n### Before calling\nAuthenticate with `gfe:write`. Resolve `patientId` in the same organization. Resolve optional `appointmentId` and `facilityId` before sending them; the current create operation visibly verifies patient ownership, not optional appointment or facility ownership.\n\n### Request guidance\n`patientId`, `providerName`, `providerNpi`, `providerTin`, `serviceDate`, and `lineItems` are required. `appointmentId`, `facilityName`, `facilityId`, `deliveryMethod`, and `signature` are optional in the public schema. Each line item requires a CPT or HCPCS-style code string of 4 to 7 characters, description, positive quantity, and positive unit charge. Keep provider TIN and line descriptions out of logs and examples unless they are synthetic.\n\n### Request notes\n- `providerNpi` must match exactly 10 digits.\n- `providerTin` is required by the request schema but is not returned in the public estimate response.\n- `serviceDate` accepts `YYYY-MM-DD` or ISO datetime input.\n- The create path rate-limits GFE generation at 100 estimates per organization per hour.\n\n### Response semantics\nA successful 201 response returns `data.estimate` and `meta.organizationId`. The operation creates local estimate status `GFE_GENERATED`, computes `totalEstimatedCost` and `patientResponsibility` from line items, and may create an underlying PDF asset. The response does not include provider TIN, patient demographics, a PDF download URL, or a storage key; use `getGoodFaithEstimatePdfUrl` for access when needed.\n\n### Response notes\n- The response is a local QuickRCM GFE, not proof of patient delivery or acknowledgment.\n- Line item totals are computed server-side from quantity and unit charge.\n- PDF generation can exist separately from immediate PDF URL retrieval.\n\n### Errors and retries\nFix validation errors before retrying. A 404 means the supplied patient was not found in the authenticated organization. A 429 can occur when the organization exceeds the GFE generation rate limit. After a timeout, list by patient or service date before creating another estimate because no idempotency key is declared.\n\n### Error notes\n- 400 can indicate missing required fields, invalid provider NPI/TIN, invalid service date, empty line items, or non-positive quantities or charges.\n- 404 means the patient identifier did not resolve in the API key organization.\n- 429 means the module-level generation limit was reached.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"string","minLength":1,"description":"Optional schema field on create. It is not returned and should not be described as bearer authentication."},"patientId":{"type":"string","minLength":1,"description":"Required QuickRCM patient identifier. The patient must belong to the API key organization."},"appointmentId":{"type":"string","minLength":1,"description":"Optional QuickRCM appointment identifier to associate with the estimate. Resolve it in the same organization before sending."},"providerName":{"type":"string","minLength":1,"maxLength":255,"description":"Required provider display name used on the estimate."},"providerNpi":{"type":"string","pattern":"^\\d{10}$","description":"Required 10-digit provider National Provider Identifier."},"providerTin":{"type":"string","minLength":9,"maxLength":11,"description":"Required provider tax identifier accepted by the request schema. It is not included in public estimate responses."},"facilityName":{"type":"string","minLength":1,"maxLength":255,"description":"Optional facility display name."},"facilityId":{"type":"string","minLength":1,"description":"Optional QuickRCM facility identifier stored on the estimate when supplied. Resolve it in the same organization before sending."},"serviceDate":{"type":"string","minLength":1,"description":"Required planned service date as `YYYY-MM-DD` or ISO datetime input."},"deliveryMethod":{"type":"string","enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"],"description":"Optional intended or recorded delivery method enum."},"lineItems":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string","minLength":4,"maxLength":7,"description":"Current Procedural Terminology (CPT) or CPT-like procedure code used by Contract Management simulation and fee schedule import entries. The public schema caps this at 20 characters."},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"quantity":{"type":"number","exclusiveMinimum":0,"description":"Positive service quantity for a line item."},"unitCharge":{"type":"number","exclusiveMinimum":0,"description":"Positive unit charge for a line item. Server-side logic computes `totalCharge`."}},"required":["cptCode","description","quantity","unitCharge"]},"minItems":1,"maxItems":100,"description":"Required array of 1 through 100 estimate line items."}},"required":["patientId","providerName","providerNpi","providerTin","serviceDate","lineItems"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","providerName":"Example good_faith_estimate","providerNpi":"1234567893","providerTin":"example-providertin","serviceDate":"2026-06-08","lineItems":[{"cptCode":"example-cptcode","description":"Example good_faith_estimate note","quantity":1.25,"unitCharge":125.5}],"signature":"example-signature","appointmentId":"00000000-0000-4000-8000-000000000001","facilityName":"Example good_faith_estimate","facilityId":"00000000-0000-4000-8000-000000000001","deliveryMethod":"GFE_DEL_EMAIL"}}},"description":"`patientId`, `providerName`, `providerNpi`, `providerTin`, `serviceDate`, and `lineItems` are required. `appointmentId`, `facilityName`, `facilityId`, `deliveryMethod`, and `signature` are optional in the public schema. Each line item requires a CPT or HCPCS-style code string of 4 to 7 characters, description, positive quantity, and positive unit charge. Keep provider TIN and line descriptions out of logs and examples unless they are synthetic."},"responses":{"201":{"description":"Good Faith Estimate created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"estimate":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"estimateNumber":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["GFE_DRAFT","GFE_GENERATED","GFE_DELIVERED","GFE_ACKNOWLEDGED","GFE_DISPUTED","GFE_EXPIRED","GFE_VOID"]},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"facilityName":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"serviceDate":{"type":["string","null"],"format":"date-time"},"lineItems":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"unitCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"providerType":{"type":["string","null"]}},"required":["cptCode","description","quantity","unitCharge","totalCharge","providerName","providerNpi","providerType"]}},"totalEstimatedCost":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"patientResponsibility":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"deliveryMethod":{"type":["string","null"],"enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"]},"deliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryDeadline":{"type":["string","null"],"format":"date-time"},"isDeliveryOverdue":{"type":"boolean"},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"disputedAt":{"type":["string","null"],"format":"date-time"},"idrCase":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"]},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"estimatedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"resolvedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"qualifyingPaymentAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"providerOfferAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payerCounterAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"arbitrationAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"initiatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","status","billedAmount","estimatedAmount","resolvedAmount","qualifyingPaymentAmount","providerOfferAmount","payerCounterAmount","arbitrationAmount","initiatedAt","resolvedAt","createdAt","updatedAt"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","estimateNumber","patientId","appointmentId","status","providerName","providerNpi","facilityName","facilityId","serviceDate","lineItems","totalEstimatedCost","patientResponsibility","deliveryMethod","deliveredAt","deliveryDeadline","isDeliveryOverdue","acknowledgedAt","disputedAt","idrCase","createdAt","updatedAt"]}},"required":["estimate"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"estimate":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","estimateNumber":"example-estimatenumber","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"GFE_DRAFT","providerName":"Example good_faith_estimate","providerNpi":"1234567893","facilityName":"Example good_faith_estimate","facilityId":"00000000-0000-4000-8000-000000000001","serviceDate":"2026-06-08T10:15:30Z","lineItems":[{"cptCode":"example-cptcode","description":"Example good_faith_estimate note","quantity":1.25,"unitCharge":"example-unitcharge","totalCharge":"example-totalcharge","providerName":"Example good_faith_estimate","providerNpi":"1234567893","providerType":"example-providertype"}],"totalEstimatedCost":"example-totalestimatedcost","patientResponsibility":"example-patientresponsibility","deliveryMethod":"GFE_DEL_EMAIL","deliveredAt":"2026-06-08T10:15:30Z","deliveryDeadline":"2026-06-08T10:15:30Z","isDeliveryOverdue":true,"acknowledgedAt":"2026-06-08T10:15:30Z","disputedAt":"2026-06-08T10:15:30Z","idrCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"IDR_INITIATED","billedAmount":"example-billedamount","estimatedAmount":"example-estimatedamount","resolvedAmount":"example-resolvedamount","qualifyingPaymentAmount":"example-qualifyingpaymentamount","providerOfferAmount":"example-providerofferamount","payerCounterAmount":"example-payercounteramount","arbitrationAmount":"example-arbitrationamount","initiatedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}}}}},"/api/v1/gfe/estimates/{gfeId}":{"get":{"operationId":"getGoodFaithEstimate","summary":"Get a Good Faith Estimate","description":"Returns one organization-scoped Good Faith Estimate summary, including public line items and a linked IDR case summary when the estimate detail query includes one.\n\n### When to use\nUse this after listing estimates, creating an estimate, delivery, acknowledgment, voiding, or dispute creation when you need the current local estimate state and linked IDR details.\n\n### Before calling\nAuthenticate with `gfe:read` or `gfe:write` and use a `gfeId` obtained from the same API-key organization context.\n\n### Request guidance\nPass `gfeId` in the path. There is no request body and no public organization selector.\n\n### Request notes\n- `gfeId` is required in the path.\n- No query parameters are defined for this endpoint.\n- Use IDs returned by trusted QuickRCM responses in the same tenant context.\n\n### Response semantics\nThe response returns `data.estimate` and `meta.organizationId`. It includes public estimate metadata and a linked `idrCase` if one exists on the estimate. It intentionally omits provider TIN, patient names, raw PDF keys, acknowledgment signature values, dispute reason text, notes, arbitration decision text, and raw file payloads. Example line-item totals should add up to `totalEstimatedCost`; `patientResponsibility` is returned as a separate stored money field.\n\n### Response notes\n- `lineItems` contains public service code, description, quantity, charge, and optional per-line provider fields.\n- `idrCase` contains local IDR status and financial summary fields when present.\n- Monetary values are serialized as strings.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization estimate context. Retry only transient infrastructure failures; do not guess estimate identifiers across organizations.\n\n### Error notes\n- 404 can intentionally hide estimates outside the authenticated organization.\n- 401 and 403 require credential, scope, or tenant-context correction.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"gfeId","in":"path","description":"QuickRCM Good Faith Estimate identifier from the path. It must belong to the API key organization."}],"responses":{"200":{"description":"Good Faith Estimate","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"estimate":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"estimateNumber":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["GFE_DRAFT","GFE_GENERATED","GFE_DELIVERED","GFE_ACKNOWLEDGED","GFE_DISPUTED","GFE_EXPIRED","GFE_VOID"]},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"facilityName":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"serviceDate":{"type":["string","null"],"format":"date-time"},"lineItems":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"unitCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"providerType":{"type":["string","null"]}},"required":["cptCode","description","quantity","unitCharge","totalCharge","providerName","providerNpi","providerType"]}},"totalEstimatedCost":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"patientResponsibility":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"deliveryMethod":{"type":["string","null"],"enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"]},"deliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryDeadline":{"type":["string","null"],"format":"date-time"},"isDeliveryOverdue":{"type":"boolean"},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"disputedAt":{"type":["string","null"],"format":"date-time"},"idrCase":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"]},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"estimatedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"resolvedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"qualifyingPaymentAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"providerOfferAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payerCounterAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"arbitrationAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"initiatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","status","billedAmount","estimatedAmount","resolvedAmount","qualifyingPaymentAmount","providerOfferAmount","payerCounterAmount","arbitrationAmount","initiatedAt","resolvedAt","createdAt","updatedAt"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","estimateNumber","patientId","appointmentId","status","providerName","providerNpi","facilityName","facilityId","serviceDate","lineItems","totalEstimatedCost","patientResponsibility","deliveryMethod","deliveredAt","deliveryDeadline","isDeliveryOverdue","acknowledgedAt","disputedAt","idrCase","createdAt","updatedAt"]}},"required":["estimate"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"estimate":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","estimateNumber":"example-estimatenumber","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"GFE_DRAFT","providerName":"Example good_faith_estimate","providerNpi":"1234567893","facilityName":"Example good_faith_estimate","facilityId":"00000000-0000-4000-8000-000000000001","serviceDate":"2026-06-08T10:15:30Z","lineItems":[{"cptCode":"example-cptcode","description":"Example good_faith_estimate note","quantity":1.25,"unitCharge":"example-unitcharge","totalCharge":"example-totalcharge","providerName":"Example good_faith_estimate","providerNpi":"1234567893","providerType":"example-providertype"}],"totalEstimatedCost":"example-totalestimatedcost","patientResponsibility":"example-patientresponsibility","deliveryMethod":"GFE_DEL_EMAIL","deliveredAt":"2026-06-08T10:15:30Z","deliveryDeadline":"2026-06-08T10:15:30Z","isDeliveryOverdue":true,"acknowledgedAt":"2026-06-08T10:15:30Z","disputedAt":"2026-06-08T10:15:30Z","idrCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"IDR_INITIATED","billedAmount":"example-billedamount","estimatedAmount":"example-estimatedamount","resolvedAmount":"example-resolvedamount","qualifyingPaymentAmount":"example-qualifyingpaymentamount","providerOfferAmount":"example-providerofferamount","payerCounterAmount":"example-payercounteramount","arbitrationAmount":"example-arbitrationamount","initiatedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Good Faith Estimate not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}},"put":{"operationId":"updateGoodFaithEstimate","summary":"Update a Good Faith Estimate","description":"Updates editable fields on an organization-owned Good Faith Estimate when the current estimate is still in an editable local status.\n\n### When to use\nUse this to correct provider, facility display name, service date, line items, or patient-responsibility information before the estimate is delivered or otherwise leaves editable workflow state.\n\n### Before calling\nAuthenticate with `gfe:write`, load the current estimate, and confirm its status is `GFE_DRAFT` or `GFE_GENERATED`.\n\n### Request guidance\nSend only fields that should be replaced. The public update body supports provider fields, `facilityName`, `serviceDate`, replacement `lineItems`, `patientResponsibility`, and optional `signature`; it does not expose `patientId`, `appointmentId`, `facilityId`, delivery timestamps, acknowledgment fields, dispute fields, direct status changes, or PDF-key changes. When `lineItems` is supplied, totals are recomputed server-side and PDF regeneration may be attempted.\n\n### Request notes\n- Editable statuses are `GFE_DRAFT` and `GFE_GENERATED`.\n- `lineItems` is optional, but when present it must contain 1 through 100 valid line items.\n- `patientResponsibility` must be zero or greater when supplied.\n- `facilityId` is not part of the public update body.\n\n### Response semantics\nThe response returns the updated public estimate summary. Updating line items changes local financial totals, but this endpoint does not deliver the estimate, acknowledge it, initiate a dispute, or return a PDF URL.\n\n### Response notes\n- The returned estimate remains local QuickRCM state.\n- The response does not include provider TIN or PDF storage location.\n- Line-item provider fields may be returned when stored on updated line items.\n\n### Errors and retries\nA 400 can indicate invalid request shape or a non-editable current status. A 404 means the estimate was not found in the authenticated organization. Re-read the estimate after a timeout before retrying to avoid overwriting newer edits.\n\n### Error notes\n- 400 can indicate an invalid service date, invalid line item, or estimate status outside the editable set.\n- 404 can mean the estimate does not exist or belongs to another organization.\n- Do not retry stale updates without re-reading current state.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"gfeId","in":"path","description":"QuickRCM Good Faith Estimate identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"string","minLength":1,"description":"Optional schema field on update. It is not returned and current handler evidence does not show it being passed into the delegated update operation."},"providerName":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement provider display name."},"providerNpi":{"type":"string","pattern":"^\\d{10}$","description":"Replacement 10-digit provider NPI."},"providerTin":{"type":"string","minLength":9,"maxLength":11,"description":"Replacement provider tax identifier accepted by the request schema and omitted from public responses."},"facilityName":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement facility display name. This endpoint does not update `facilityId`."},"serviceDate":{"type":"string","minLength":1,"description":"Replacement planned service date as `YYYY-MM-DD` or ISO datetime input."},"lineItems":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string","minLength":4,"maxLength":7,"description":"Current Procedural Terminology (CPT) or CPT-like procedure code used by Contract Management simulation and fee schedule import entries. The public schema caps this at 20 characters."},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"quantity":{"type":"number","exclusiveMinimum":0,"description":"Claim-line quantity serialized as a decimal string."},"unitCharge":{"type":"number","exclusiveMinimum":0,"description":"Positive per-unit charge accepted as a request number and serialized as a money string in responses."},"providerName":{"type":"string","minLength":1,"maxLength":255,"description":"Replacement provider display name."},"providerNpi":{"type":"string","pattern":"^\\d{10}$","description":"Replacement 10-digit provider NPI."},"providerType":{"type":"string","minLength":1,"maxLength":255}},"required":["cptCode","description","quantity","unitCharge"]},"minItems":1,"maxItems":100,"description":"Optional replacement estimate lines. Totals are recomputed from quantity and unit charge."},"patientResponsibility":{"type":["number","null"],"minimum":0,"description":"Optional non-negative patient responsibility amount."}}},"example":{"signature":"example-signature","providerName":"Example good_faith_estimate","providerNpi":"1234567893","providerTin":"example-providertin","facilityName":"Example good_faith_estimate","serviceDate":"2026-06-08","lineItems":[{"cptCode":"example-cptcode","description":"Example good_faith_estimate note","quantity":1.25,"unitCharge":125.5,"providerName":"Example good_faith_estimate","providerNpi":"1234567893","providerType":"example-providertype"}],"patientResponsibility":1.25}}},"description":"Send only fields that should be replaced. The public update body supports provider fields, `facilityName`, `serviceDate`, replacement `lineItems`, `patientResponsibility`, and optional `signature`; it does not expose `patientId`, `appointmentId`, `facilityId`, delivery timestamps, acknowledgment fields, dispute fields, direct status changes, or PDF-key changes. When `lineItems` is supplied, totals are recomputed server-side and PDF regeneration may be attempted."},"responses":{"200":{"description":"Good Faith Estimate updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"estimate":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"estimateNumber":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["GFE_DRAFT","GFE_GENERATED","GFE_DELIVERED","GFE_ACKNOWLEDGED","GFE_DISPUTED","GFE_EXPIRED","GFE_VOID"]},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"facilityName":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"serviceDate":{"type":["string","null"],"format":"date-time"},"lineItems":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"unitCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"providerType":{"type":["string","null"]}},"required":["cptCode","description","quantity","unitCharge","totalCharge","providerName","providerNpi","providerType"]}},"totalEstimatedCost":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"patientResponsibility":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"deliveryMethod":{"type":["string","null"],"enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"]},"deliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryDeadline":{"type":["string","null"],"format":"date-time"},"isDeliveryOverdue":{"type":"boolean"},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"disputedAt":{"type":["string","null"],"format":"date-time"},"idrCase":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"]},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"estimatedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"resolvedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"qualifyingPaymentAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"providerOfferAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payerCounterAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"arbitrationAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"initiatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","status","billedAmount","estimatedAmount","resolvedAmount","qualifyingPaymentAmount","providerOfferAmount","payerCounterAmount","arbitrationAmount","initiatedAt","resolvedAt","createdAt","updatedAt"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","estimateNumber","patientId","appointmentId","status","providerName","providerNpi","facilityName","facilityId","serviceDate","lineItems","totalEstimatedCost","patientResponsibility","deliveryMethod","deliveredAt","deliveryDeadline","isDeliveryOverdue","acknowledgedAt","disputedAt","idrCase","createdAt","updatedAt"]}},"required":["estimate"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"estimate":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","estimateNumber":"example-estimatenumber","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"GFE_DRAFT","providerName":"Example good_faith_estimate","providerNpi":"1234567893","facilityName":"Example good_faith_estimate","facilityId":"00000000-0000-4000-8000-000000000001","serviceDate":"2026-06-08T10:15:30Z","lineItems":[{"cptCode":"example-cptcode","description":"Example good_faith_estimate note","quantity":1.25,"unitCharge":"example-unitcharge","totalCharge":"example-totalcharge","providerName":"Example good_faith_estimate","providerNpi":"1234567893","providerType":"example-providertype"}],"totalEstimatedCost":"example-totalestimatedcost","patientResponsibility":"example-patientresponsibility","deliveryMethod":"GFE_DEL_EMAIL","deliveredAt":"2026-06-08T10:15:30Z","deliveryDeadline":"2026-06-08T10:15:30Z","isDeliveryOverdue":true,"acknowledgedAt":"2026-06-08T10:15:30Z","disputedAt":"2026-06-08T10:15:30Z","idrCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"IDR_INITIATED","billedAmount":"example-billedamount","estimatedAmount":"example-estimatedamount","resolvedAmount":"example-resolvedamount","qualifyingPaymentAmount":"example-qualifyingpaymentamount","providerOfferAmount":"example-providerofferamount","payerCounterAmount":"example-payercounteramount","arbitrationAmount":"example-arbitrationamount","initiatedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Good Faith Estimate not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/gfe/estimates/{gfeId}/deliver":{"post":{"operationId":"deliverGoodFaithEstimate","summary":"Deliver a Good Faith Estimate","description":"Marks a local Good Faith Estimate as delivered, or returns a no-write simulation response when `simulateOnly` is true.\n\n### When to use\nUse this after an estimate is ready and your workflow has performed, or is about to perform, the documented delivery step through email, portal, mail, hand delivery, or fax.\n\n### Before calling\nAuthenticate with `gfe:write`, resolve the estimate in the same organization, and confirm its current status is `GFE_DRAFT` or `GFE_GENERATED` before making a live delivery request.\n\n### Request guidance\n`deliveryMethod` is required. `simulateOnly` is an optional JSON boolean in the request body. Do not describe this endpoint as sending email, fax, portal, or mail by itself; the implementation records delivery state and method.\n\n### Request notes\n- `deliveryMethod` values are `GFE_DEL_EMAIL`, `GFE_DEL_PORTAL`, `GFE_DEL_MAIL`, `GFE_DEL_HAND_DELIVERY`, and `GFE_DEL_FAX`.\n- `simulateOnly` must be a JSON boolean, not the string query style used by the PDF endpoint.\n- Live delivery is allowed only from draft or generated states; simulation mode should not be treated as proof that a live call would pass for every current status.\n\n### Response semantics\nIn simulation mode, the handler reads the current estimate and returns it with `data.simulation`; it does not mutate state and does not invoke the live delivery operation or its status checks. In live mode, the response returns the updated estimate with delivery status and timestamp fields updated by local workflow logic. Normal examples should preserve the stored line items so `lineItems[].totalCharge` sums to `totalEstimatedCost`.\n\n### Response notes\n- Simulation mode does not mutate estimate status.\n- Live mode can set `status`, `deliveredAt`, `deliveryMethod`, and `isDeliveryOverdue`.\n- The response does not include proof of external transport delivery.\n\n### Errors and retries\nA 400 can indicate an invalid delivery method or an estimate status that cannot be delivered in live mode. A 404 means the estimate is missing or outside the authenticated organization. If a live call times out, re-read the estimate before retrying because delivery state may already have changed.\n\n### Error notes\n- 400 can indicate live delivery from `GFE_DELIVERED`, `GFE_ACKNOWLEDGED`, `GFE_DISPUTED`, `GFE_EXPIRED`, or `GFE_VOID` status.\n- 404 can intentionally hide wrong-tenant estimates.\n- Re-read after uncertain live delivery failures before retrying.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"gfeId","in":"path","description":"QuickRCM Good Faith Estimate identifier in a path parameter. It must resolve inside the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"string","minLength":1,"description":"Optional request marker on several schemas. It is not bearer authentication and is not returned in public responses."},"deliveryMethod":{"type":"string","enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"],"description":"Required enum describing the delivery channel being recorded."},"simulateOnly":{"type":"boolean","description":"Optional body boolean. When true, returns a simulation block without changing estimate status."}},"required":["deliveryMethod"]},"example":{"deliveryMethod":"GFE_DEL_EMAIL","signature":"example-signature","simulateOnly":true}}},"description":"`deliveryMethod` is required. `simulateOnly` is an optional JSON boolean in the request body. Do not describe this endpoint as sending email, fax, portal, or mail by itself; the implementation records delivery state and method."},"responses":{"200":{"description":"Good Faith Estimate delivery result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"estimate":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"estimateNumber":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["GFE_DRAFT","GFE_GENERATED","GFE_DELIVERED","GFE_ACKNOWLEDGED","GFE_DISPUTED","GFE_EXPIRED","GFE_VOID"]},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"facilityName":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"serviceDate":{"type":["string","null"],"format":"date-time"},"lineItems":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"unitCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"providerType":{"type":["string","null"]}},"required":["cptCode","description","quantity","unitCharge","totalCharge","providerName","providerNpi","providerType"]}},"totalEstimatedCost":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"patientResponsibility":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"deliveryMethod":{"type":["string","null"],"enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"]},"deliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryDeadline":{"type":["string","null"],"format":"date-time"},"isDeliveryOverdue":{"type":"boolean"},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"disputedAt":{"type":["string","null"],"format":"date-time"},"idrCase":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"]},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"estimatedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"resolvedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"qualifyingPaymentAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"providerOfferAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payerCounterAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"arbitrationAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"initiatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","status","billedAmount","estimatedAmount","resolvedAmount","qualifyingPaymentAmount","providerOfferAmount","payerCounterAmount","arbitrationAmount","initiatedAt","resolvedAt","createdAt","updatedAt"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","estimateNumber","patientId","appointmentId","status","providerName","providerNpi","facilityName","facilityId","serviceDate","lineItems","totalEstimatedCost","patientResponsibility","deliveryMethod","deliveredAt","deliveryDeadline","isDeliveryOverdue","acknowledgedAt","disputedAt","idrCase","createdAt","updatedAt"]},"simulation":{"type":"object","properties":{"mode":{"type":"string","enum":["simulated"]},"deliveryMethod":{"type":"string","enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"]},"wouldSetStatus":{"type":"string","enum":["GFE_DELIVERED"]}},"required":["mode","deliveryMethod","wouldSetStatus"]}},"required":["estimate"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"estimate":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","estimateNumber":"example-estimatenumber","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"GFE_DRAFT","providerName":"Example deliver_good_faith_estimate","providerNpi":"1234567893","facilityName":"Example deliver_good_faith_estimate","facilityId":"00000000-0000-4000-8000-000000000001","serviceDate":"2026-06-08T10:15:30Z","lineItems":[{"cptCode":"example-cptcode","description":"Example deliver_good_faith_estimate note","quantity":1.25,"unitCharge":"example-unitcharge","totalCharge":"example-totalcharge","providerName":"Example deliver_good_faith_estimate","providerNpi":"1234567893","providerType":"example-providertype"}],"totalEstimatedCost":"example-totalestimatedcost","patientResponsibility":"example-patientresponsibility","deliveryMethod":"GFE_DEL_EMAIL","deliveredAt":"2026-06-08T10:15:30Z","deliveryDeadline":"2026-06-08T10:15:30Z","isDeliveryOverdue":true,"acknowledgedAt":"2026-06-08T10:15:30Z","disputedAt":"2026-06-08T10:15:30Z","idrCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"IDR_INITIATED","billedAmount":"example-billedamount","estimatedAmount":"example-estimatedamount","resolvedAmount":"example-resolvedamount","qualifyingPaymentAmount":"example-qualifyingpaymentamount","providerOfferAmount":"example-providerofferamount","payerCounterAmount":"example-payercounteramount","arbitrationAmount":"example-arbitrationamount","initiatedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"simulation":{"mode":"simulated","deliveryMethod":"GFE_DEL_EMAIL","wouldSetStatus":"GFE_DELIVERED"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Good Faith Estimate not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/gfe/estimates/{gfeId}/acknowledge":{"post":{"operationId":"acknowledgeGoodFaithEstimate","summary":"Acknowledge a Good Faith Estimate","description":"Records patient acknowledgment for an organization-owned Good Faith Estimate that is currently in delivered status.\n\n### When to use\nUse this after the patient or authorized workflow confirms receipt or acknowledgment of a delivered GFE.\n\n### Before calling\nAuthenticate with `gfe:write`, resolve the estimate in the same organization, and confirm the current status is `GFE_DELIVERED`.\n\n### Request guidance\nThe body may include an optional `signature` string up to 255 characters. Keep this value synthetic in examples and avoid using it for secrets or credentials. No organization selector is accepted.\n\n### Request notes\n- `signature` is optional and capped at 255 characters.\n- The endpoint does not accept a delivery method or status override.\n- The estimate must already be delivered.\n\n### Response semantics\nA successful response returns the updated estimate with status `GFE_ACKNOWLEDGED` and an acknowledgment timestamp. The signature value is not included in the public estimate response.\n\n### Response notes\n- `acknowledgedAt` is set in the returned estimate when acknowledgment succeeds.\n- Acknowledgment is local QuickRCM workflow state.\n- The response omits the submitted signature.\n\n### Errors and retries\nA 400 can indicate the estimate is not in delivered status. A 404 means the estimate is unavailable to the authenticated organization. Re-read current state before retrying after uncertain network failures.\n\n### Error notes\n- 400 can mean the current status is not `GFE_DELIVERED`.\n- 404 can mean the estimate is missing or outside the tenant.\n- Do not describe `signature` as authentication.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"gfeId","in":"path","description":"QuickRCM Good Faith Estimate identifier in a path parameter. It must resolve inside the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"string","minLength":1,"maxLength":255,"description":"Optional acknowledgment signature or marker. Do not use it to carry secrets or long clinical notes."}}},"example":{"signature":"example-signature"}}},"description":"The body may include an optional `signature` string up to 255 characters. Keep this value synthetic in examples and avoid using it for secrets or credentials. No organization selector is accepted."},"responses":{"200":{"description":"Good Faith Estimate acknowledged","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"estimate":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"estimateNumber":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["GFE_DRAFT","GFE_GENERATED","GFE_DELIVERED","GFE_ACKNOWLEDGED","GFE_DISPUTED","GFE_EXPIRED","GFE_VOID"]},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"facilityName":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"serviceDate":{"type":["string","null"],"format":"date-time"},"lineItems":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"unitCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"providerType":{"type":["string","null"]}},"required":["cptCode","description","quantity","unitCharge","totalCharge","providerName","providerNpi","providerType"]}},"totalEstimatedCost":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"patientResponsibility":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"deliveryMethod":{"type":["string","null"],"enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"]},"deliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryDeadline":{"type":["string","null"],"format":"date-time"},"isDeliveryOverdue":{"type":"boolean"},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"disputedAt":{"type":["string","null"],"format":"date-time"},"idrCase":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"]},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"estimatedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"resolvedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"qualifyingPaymentAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"providerOfferAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payerCounterAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"arbitrationAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"initiatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","status","billedAmount","estimatedAmount","resolvedAmount","qualifyingPaymentAmount","providerOfferAmount","payerCounterAmount","arbitrationAmount","initiatedAt","resolvedAt","createdAt","updatedAt"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","estimateNumber","patientId","appointmentId","status","providerName","providerNpi","facilityName","facilityId","serviceDate","lineItems","totalEstimatedCost","patientResponsibility","deliveryMethod","deliveredAt","deliveryDeadline","isDeliveryOverdue","acknowledgedAt","disputedAt","idrCase","createdAt","updatedAt"]}},"required":["estimate"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"estimate":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","estimateNumber":"example-estimatenumber","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"GFE_DRAFT","providerName":"Example acknowledge_good_faith_estimate","providerNpi":"1234567893","facilityName":"Example acknowledge_good_faith_estimate","facilityId":"00000000-0000-4000-8000-000000000001","serviceDate":"2026-06-08T10:15:30Z","lineItems":[{"cptCode":"example-cptcode","description":"Example acknowledge_good_faith_estimate note","quantity":1.25,"unitCharge":"example-unitcharge","totalCharge":"example-totalcharge","providerName":"Example acknowledge_good_faith_estimate","providerNpi":"1234567893","providerType":"example-providertype"}],"totalEstimatedCost":"example-totalestimatedcost","patientResponsibility":"example-patientresponsibility","deliveryMethod":"GFE_DEL_EMAIL","deliveredAt":"2026-06-08T10:15:30Z","deliveryDeadline":"2026-06-08T10:15:30Z","isDeliveryOverdue":true,"acknowledgedAt":"2026-06-08T10:15:30Z","disputedAt":"2026-06-08T10:15:30Z","idrCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"IDR_INITIATED","billedAmount":"example-billedamount","estimatedAmount":"example-estimatedamount","resolvedAmount":"example-resolvedamount","qualifyingPaymentAmount":"example-qualifyingpaymentamount","providerOfferAmount":"example-providerofferamount","payerCounterAmount":"example-payercounteramount","arbitrationAmount":"example-arbitrationamount","initiatedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Good Faith Estimate not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/gfe/estimates/{gfeId}/disputes":{"post":{"operationId":"initiateGfeDispute","summary":"Initiate a GFE dispute","description":"Creates a local IDR case for an acknowledged Good Faith Estimate when the billed amount exceeds the estimate by at least the module's dispute threshold.\n\n### When to use\nUse this when a qualifying billed amount difference has been identified and QuickRCM needs to track a local IDR workflow against an acknowledged GFE.\n\n### Before calling\nAuthenticate with `gfe:write`, confirm the GFE is in `GFE_ACKNOWLEDGED` status, confirm no IDR case already exists for it, and calculate whether `billedAmount - totalEstimatedCost` is at least 400.\n\n### Request guidance\n`disputeReason` and `billedAmount` are required. `billedAmount` must be positive. Keep the dispute reason concise and free of unnecessary PHI, payer credentials, raw EDI, transcripts, S3 keys, or portal payloads.\n\n### Request notes\n- `disputeReason` is required and capped at 2000 characters by the public schema.\n- `billedAmount` is a positive number.\n- The current local threshold is a difference of at least 400 above the estimate total.\n\n### Response semantics\nA successful 201 response returns `data.idrCase` and `meta.organizationId`. The operation updates the GFE to disputed and creates local IDR case status `IDR_INITIATED`, but the immediate response body returns the IDR case summary, not the full updated estimate.\n\n### Response notes\n- `data.idrCase.status` is `IDR_INITIATED` on creation.\n- The IDR case response includes financial summary fields and timestamps, not dispute reason text.\n- This endpoint does not submit a dispute to an external IDR entity.\n\n### Errors and retries\nA 400 can indicate invalid input, a non-acknowledged GFE, or a billed amount difference below the threshold. A 409 means an IDR case already exists for the GFE. After timeouts, fetch the estimate before retrying to avoid duplicate dispute attempts.\n\n### Error notes\n- 400 can mean the estimate is not acknowledged or the billed amount does not exceed the estimate by the required threshold.\n- 409 means a local IDR case already exists for this GFE.\n- 404 can intentionally hide wrong-tenant estimates.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"gfeId","in":"path","description":"QuickRCM Good Faith Estimate identifier in a path parameter. It must resolve inside the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"string","minLength":1,"description":"Optional request marker on several schemas. It is not bearer authentication and is not returned in public responses."},"disputeReason":{"type":"string","minLength":1,"maxLength":2000,"description":"Required reason text for local dispute creation. Keep it concise and sanitized."},"billedAmount":{"type":"number","exclusiveMinimum":0,"description":"Required billed amount used to test the dispute threshold against the estimate total."}},"required":["disputeReason","billedAmount"]},"example":{"disputeReason":"example-disputereason","billedAmount":125.5,"signature":"example-signature"}}},"description":"`disputeReason` and `billedAmount` are required. `billedAmount` must be positive. Keep the dispute reason concise and free of unnecessary PHI, payer credentials, raw EDI, transcripts, S3 keys, or portal payloads."},"responses":{"201":{"description":"IDR case created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"idrCase":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"]},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"estimatedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"resolvedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"qualifyingPaymentAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"providerOfferAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payerCounterAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"arbitrationAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"initiatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","status","billedAmount","estimatedAmount","resolvedAmount","qualifyingPaymentAmount","providerOfferAmount","payerCounterAmount","arbitrationAmount","initiatedAt","resolvedAt","createdAt","updatedAt"]}},"required":["idrCase"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"idrCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"IDR_INITIATED","billedAmount":"example-billedamount","estimatedAmount":"example-estimatedamount","resolvedAmount":"example-resolvedamount","qualifyingPaymentAmount":"example-qualifyingpaymentamount","providerOfferAmount":"example-providerofferamount","payerCounterAmount":"example-payercounteramount","arbitrationAmount":"example-arbitrationamount","initiatedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Good Faith Estimate not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"IDR case already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}}}}},"/api/v1/gfe/idr-cases/{idrCaseId}":{"put":{"operationId":"updateGfeIdrCase","summary":"Update a GFE IDR case","description":"Updates local status and safe financial tracking fields on an organization-owned GFE IDR case.\n\n### When to use\nUse this as the IDR workflow moves through offer, counter, arbitration, resolution, or withdrawal states, or when safe amount fields need to be recorded.\n\n### Before calling\nAuthenticate with `gfe:write`, resolve `idrCaseId` from the same organization, and know the current IDR status before requesting a transition.\n\n### Request guidance\nAll body fields are optional, but callers should send at least the status or amount field they intend to update. Status transitions are validated against the module state machine. `notes` and `arbitrationDecision` are accepted as local text fields but are sanitized and are not returned in the public response.\n\n### Request notes\n- Allowed statuses are `IDR_INITIATED`, `IDR_OFFER_SUBMITTED`, `IDR_COUNTER_RECEIVED`, `IDR_ARBITRATION`, `IDR_RESOLVED_PROVIDER`, `IDR_RESOLVED_PAYER`, `IDR_RESOLVED_SPLIT`, and `IDR_WITHDRAWN`.\n- Allowed transitions are initiated to offer submitted or withdrawn; offer submitted to counter received, resolved provider, or withdrawn; counter received to arbitration, resolved payer, resolved split, or withdrawn; arbitration to resolved provider, resolved payer, or resolved split.\n- Amount fields must be zero or greater when supplied.\n- Amount-only updates are accepted when one or more safe financial fields are present; avoid sending an empty body because it has no useful workflow effect.\n\n### Response semantics\nThe response returns `data.idrCase`, including IDR status, billed and estimated amounts, offer/counter/arbitration/resolved amounts, qualifying payment amount, and timestamps. It does not include notes or arbitration decision text and is not evidence of external arbitration outcome unless a separate approved workflow records that fact.\n\n### Response notes\n- `resolvedAt` is set when the operation moves the case to a resolved or withdrawn status.\n- The response contains local workflow state only.\n- Text fields accepted in the request are not echoed in the public response.\n\n### Errors and retries\nA 400 can indicate an invalid status enum, invalid status transition, or invalid field value. A 404 means the IDR case is missing or outside the authenticated organization. Re-read the case after timeouts before replaying updates.\n\n### Error notes\n- 400 can indicate an invalid status transition such as moving directly from initiated to arbitration.\n- 404 can mean the IDR case does not belong to the API key organization.\n- Do not claim this endpoint files or resolves an external arbitration case.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"idrCaseId","in":"path","description":"QuickRCM IDR case identifier from the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"string","minLength":1,"description":"Optional schema field on IDR update. It is not returned and should not be used for authentication."},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"],"description":"Optional requested local IDR status. Transitions are validated from the current stored status."},"providerOfferAmount":{"type":["number","null"],"minimum":0,"description":"Optional non-negative provider offer amount retained on the local IDR case."},"payerCounterAmount":{"type":["number","null"],"minimum":0,"description":"Optional non-negative payer counter amount retained on the local IDR case."},"arbitrationDecision":{"type":"string","minLength":1,"maxLength":4000,"description":"Optional local decision text accepted by the public schema and sanitized before storage. It is not returned in the public response."},"arbitrationAmount":{"type":["number","null"],"minimum":0,"description":"Optional non-negative arbitration amount."},"resolvedAmount":{"type":["number","null"],"minimum":0,"description":"Optional non-negative resolved amount."},"qualifyingPaymentAmount":{"type":["number","null"],"minimum":0,"description":"Optional non-negative qualifying payment amount."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional local notes capped by the public schema and sanitized before storage. Notes are not returned in public IDR case responses."}}},"example":{"signature":"example-signature","status":"IDR_INITIATED","providerOfferAmount":125.5,"payerCounterAmount":1,"arbitrationDecision":"example-arbitrationdecision","arbitrationAmount":125.5,"resolvedAmount":125.5,"qualifyingPaymentAmount":125.5}}},"description":"All body fields are optional, but callers should send at least the status or amount field they intend to update. Status transitions are validated against the module state machine. `notes` and `arbitrationDecision` are accepted as local text fields but are sanitized and are not returned in the public response."},"responses":{"200":{"description":"IDR case updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"idrCase":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"]},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"estimatedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"resolvedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"qualifyingPaymentAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"providerOfferAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payerCounterAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"arbitrationAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"initiatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","status","billedAmount","estimatedAmount","resolvedAmount","qualifyingPaymentAmount","providerOfferAmount","payerCounterAmount","arbitrationAmount","initiatedAt","resolvedAt","createdAt","updatedAt"]}},"required":["idrCase"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"idrCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"IDR_INITIATED","billedAmount":"example-billedamount","estimatedAmount":"example-estimatedamount","resolvedAmount":"example-resolvedamount","qualifyingPaymentAmount":"example-qualifyingpaymentamount","providerOfferAmount":"example-providerofferamount","payerCounterAmount":"example-payercounteramount","arbitrationAmount":"example-arbitrationamount","initiatedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"IDR case not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/gfe/estimates/{gfeId}/void":{"post":{"operationId":"voidGoodFaithEstimate","summary":"Void a Good Faith Estimate","description":"Voids a local Good Faith Estimate in a voidable status and records the void reason in local audit context.\n\n### When to use\nUse this when a draft, generated, or delivered estimate should no longer be active because it was created in error, superseded, or otherwise invalid for workflow purposes.\n\n### Before calling\nAuthenticate with `gfe:write`, load the estimate, and confirm the current status is `GFE_DRAFT`, `GFE_GENERATED`, or `GFE_DELIVERED`.\n\n### Request guidance\n`voidReason` is required and capped at 2000 characters by the public schema. Keep the reason operational and do not include payer credentials, raw EDI, transcripts, S3 keys, or unnecessary PHI.\n\n### Request notes\n- `voidReason` is required.\n- Voidable statuses are `GFE_DRAFT`, `GFE_GENERATED`, and `GFE_DELIVERED`.\n- The endpoint records local workflow state; it is not a delete operation.\n\n### Response semantics\nThe response returns the updated estimate with status `GFE_VOID`. Voiding is a local status transition; it does not delete the estimate, delete a PDF asset, reverse patient acknowledgment, or close an existing IDR case.\n\n### Response notes\n- Returned `data.estimate.status` is `GFE_VOID` on success.\n- The public response does not return the void reason.\n- Voided estimates remain visible through normal list/detail access unless filtered out by callers.\n\n### Errors and retries\nA 400 can indicate an invalid or empty void reason or a non-voidable status. A 404 means the estimate was not found in the authenticated organization. Re-read current status before retrying after a timeout.\n\n### Error notes\n- 400 can mean the current status is acknowledged, disputed, expired, or already void.\n- 404 can intentionally hide wrong-tenant estimates.\n- Do not document voiding as deleting PDF files or estimate rows.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"gfeId","in":"path","description":"QuickRCM Good Faith Estimate identifier in a path parameter. It must resolve inside the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signature":{"type":"string","minLength":1,"description":"Optional request marker on several schemas. It is not bearer authentication and is not returned in public responses."},"voidReason":{"type":"string","minLength":1,"maxLength":2000,"description":"Required local reason for voiding the estimate. It is sanitized and not returned in public estimate responses."}},"required":["voidReason"]},"example":{"voidReason":"example-voidreason","signature":"example-signature"}}},"description":"`voidReason` is required and capped at 2000 characters by the public schema. Keep the reason operational and do not include payer credentials, raw EDI, transcripts, S3 keys, or unnecessary PHI."},"responses":{"200":{"description":"Good Faith Estimate voided","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"estimate":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"estimateNumber":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["GFE_DRAFT","GFE_GENERATED","GFE_DELIVERED","GFE_ACKNOWLEDGED","GFE_DISPUTED","GFE_EXPIRED","GFE_VOID"]},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"facilityName":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"serviceDate":{"type":["string","null"],"format":"date-time"},"lineItems":{"type":"array","items":{"type":"object","properties":{"cptCode":{"type":"string"},"description":{"type":"string"},"quantity":{"type":"number"},"unitCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalCharge":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"providerName":{"type":["string","null"]},"providerNpi":{"type":["string","null"]},"providerType":{"type":["string","null"]}},"required":["cptCode","description","quantity","unitCharge","totalCharge","providerName","providerNpi","providerType"]}},"totalEstimatedCost":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"patientResponsibility":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"deliveryMethod":{"type":["string","null"],"enum":["GFE_DEL_EMAIL","GFE_DEL_PORTAL","GFE_DEL_MAIL","GFE_DEL_HAND_DELIVERY","GFE_DEL_FAX"]},"deliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryDeadline":{"type":["string","null"],"format":"date-time"},"isDeliveryOverdue":{"type":"boolean"},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"disputedAt":{"type":["string","null"],"format":"date-time"},"idrCase":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["IDR_INITIATED","IDR_OFFER_SUBMITTED","IDR_COUNTER_RECEIVED","IDR_ARBITRATION","IDR_RESOLVED_PROVIDER","IDR_RESOLVED_PAYER","IDR_RESOLVED_SPLIT","IDR_WITHDRAWN"]},"billedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"estimatedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"resolvedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"qualifyingPaymentAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"providerOfferAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"payerCounterAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"arbitrationAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"initiatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","status","billedAmount","estimatedAmount","resolvedAmount","qualifyingPaymentAmount","providerOfferAmount","payerCounterAmount","arbitrationAmount","initiatedAt","resolvedAt","createdAt","updatedAt"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","estimateNumber","patientId","appointmentId","status","providerName","providerNpi","facilityName","facilityId","serviceDate","lineItems","totalEstimatedCost","patientResponsibility","deliveryMethod","deliveredAt","deliveryDeadline","isDeliveryOverdue","acknowledgedAt","disputedAt","idrCase","createdAt","updatedAt"]}},"required":["estimate"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"estimate":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","estimateNumber":"example-estimatenumber","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"GFE_DRAFT","providerName":"Example void_good_faith_estimate","providerNpi":"1234567893","facilityName":"Example void_good_faith_estimate","facilityId":"00000000-0000-4000-8000-000000000001","serviceDate":"2026-06-08T10:15:30Z","lineItems":[{"cptCode":"example-cptcode","description":"Example void_good_faith_estimate note","quantity":1.25,"unitCharge":"example-unitcharge","totalCharge":"example-totalcharge","providerName":"Example void_good_faith_estimate","providerNpi":"1234567893","providerType":"example-providertype"}],"totalEstimatedCost":"example-totalestimatedcost","patientResponsibility":"example-patientresponsibility","deliveryMethod":"GFE_DEL_EMAIL","deliveredAt":"2026-06-08T10:15:30Z","deliveryDeadline":"2026-06-08T10:15:30Z","isDeliveryOverdue":true,"acknowledgedAt":"2026-06-08T10:15:30Z","disputedAt":"2026-06-08T10:15:30Z","idrCase":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"IDR_INITIATED","billedAmount":"example-billedamount","estimatedAmount":"example-estimatedamount","resolvedAmount":"example-resolvedamount","qualifyingPaymentAmount":"example-qualifyingpaymentamount","providerOfferAmount":"example-providerofferamount","payerCounterAmount":"example-payercounteramount","arbitrationAmount":"example-arbitrationamount","initiatedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Good Faith Estimate not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/gfe/estimates/{gfeId}/pdf-url":{"get":{"operationId":"getGoodFaithEstimatePdfUrl","summary":"Get a Good Faith Estimate PDF URL","description":"Returns PDF availability for a Good Faith Estimate and, outside simulation mode, PDF download access when a stored PDF key exists.\n\n### When to use\nUse this after creating or retrieving an estimate when a client needs to download or hand off the generated GFE PDF.\n\n### Before calling\nAuthenticate with `gfe:read` or `gfe:write` and resolve `gfeId` from the same organization. Use `simulateOnly=true` when checking whether a PDF key exists without receiving a live download URL.\n\n### Request guidance\n`simulateOnly` is an optional query string value of `true` or `false`. There is no request body. Do not log or persist live `downloadUrl` values; they are temporary access links or sensitive data URLs, not stable file identifiers.\n\n### Request notes\n- `simulateOnly` is a query string, unlike deliver's body boolean.\n- Live S3 download URLs expire after 300 seconds; local fallback data URLs should still be handled as sensitive PDF content.\n- No PDF storage key is returned.\n\n### Response semantics\nSimulation mode checks only the estimate's stored PDF key presence and returns `mode: simulated`, `pdfAvailable`, `downloadUrl: null`, and `expiresInSeconds: null`. Live mode calls the PDF download operation and returns `mode: live`, `pdfAvailable: true`, a download URL, and `expiresInSeconds: 300`. For local fallback keys, live mode reads the local PDF and returns a `data:application/pdf;base64,...` URL; if that local file is missing, the endpoint returns 404. For S3-backed keys, live mode issues a presigned URL for the stored key and does not prove that the remote object will download successfully. The response never exposes the underlying PDF storage key.\n\n### Response notes\n- `downloadUrl` is null in simulation mode.\n- `pdfAvailable` in simulation mode only reflects stored PDF-key presence, not a live file read or remote-object retrieval.\n- Treat live URLs and PDF data URLs as sensitive temporary access values.\n- For S3-backed keys, a successful API response means a presigned URL was issued; the endpoint does not prove the downstream object download will succeed.\n\n### Errors and retries\nA 404 can mean the estimate is missing or outside the authenticated organization, no PDF key has been generated for the estimate, or a local fallback PDF file cannot be read. S3-backed live responses issue a presigned URL for the stored key and do not verify remote object availability before returning. Retry transient server or storage-configuration failures with backoff, but do not retry missing-PDF cases until the estimate or PDF generation state changes.\n\n### Error notes\n- 404 can indicate `Good Faith Estimate not found`, `PDF not generated for this GFE`, or `PDF file not found for this GFE` for local fallback reads.\n- Do not document S3-object absence as an API-level 404 condition unless the implementation adds an object-existence check.\n- A missing or misconfigured S3 bucket is a server/storage configuration failure, not a caller-correctable request error.\n- 401 and 403 require credential, scope, or tenant-context correction.\n","tags":["Good Faith Estimates"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"gfeId","in":"path","description":"QuickRCM Good Faith Estimate identifier in a path parameter. It must resolve inside the authenticated organization."},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"simulateOnly","in":"query","description":"Optional query string. Use `true` to check PDF-key presence without returning a live URL."}],"responses":{"200":{"description":"Good Faith Estimate PDF URL result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"estimateId":{"type":"string"},"mode":{"type":"string","enum":["simulated","live"]},"pdfAvailable":{"type":"boolean"},"downloadUrl":{"type":["string","null"]},"expiresInSeconds":{"type":["integer","null"],"exclusiveMinimum":0}},"required":["estimateId","mode","pdfAvailable","downloadUrl","expiresInSeconds"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"estimateId":"00000000-0000-4000-8000-000000000001","mode":"simulated","pdfAvailable":true,"downloadUrl":"https://example.quickintell.com/resource","expiresInSeconds":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Good Faith Estimate PDF not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/insurance-discovery/searches":{"get":{"operationId":"listInsuranceDiscoverySearches","summary":"List insurance discovery searches","description":"Lists local insurance discovery search records owned by the organization selected by the bearer API key.\n\n### When to use\nUse this endpoint to build discovery worklists, review recent search outcomes, find searches by patient or batch, or page through local discovery history before verifying, dismissing, or retrying a specific search.\n\n### Before calling\nAuthenticate with an API key authorized for Insurance Discovery reads. Choose narrow filters where possible: `status`, `batchId`, `patientId`, `searchTerm`, `skip`, and `take`.\n\n### Request guidance\n`status`, `batchId`, `patientId`, and `searchTerm` are optional filters. `searchTerm` is trimmed, must be 1 to 200 characters when supplied, and can match patient or payer context, so avoid logging it. `skip` defaults to 0 and must be an integer from 0 through 10000. `take` defaults to 25 and must be an integer from 1 through 100. Do not send `organizationId`; the API key selects the tenant.\n\n### Request notes\n- `status` accepts `DISC_PENDING`, `DISC_SEARCHING`, `DISC_FOUND`, `DISC_NOT_FOUND`, `DISC_VERIFIED`, `DISC_FAILED`, `DISC_EXPIRED`, and `DISC_DISMISSED`.\n- Use `patientId` or `batchId` when reconciling a known workflow to avoid broad exports.\n- Read endpoints accept either `insurance-discovery:read` or `insurance-discovery:write` scope according to the public API handler.\n\n### Response semantics\nHTTP 200 returns `data.searches`, `total`, `skip`, `take`, and `meta.organizationId`. Search rows are local QuickRCM records with status, trigger, optional source, optional found coverage summary, lifecycle timestamps, and local linkage identifiers. `meta.organizationId` is response context, not a request-time tenant selector.\n\n### Response notes\n- `foundCoverage` is a local discovery result summary; it is not eligibility verification or payer acceptance.\n- `patientInsuranceId` is populated only after verified coverage is linked locally.\n- Use `getInsuranceDiscoverySearch` for one search before state-changing actions.\n\n### Errors and retries\nTreat 400 as invalid filters or pagination bounds, 401 as missing or invalid credentials, 403 as tenant, scope, or permission failure, and 429 as a backoff signal. Retry transient 5xx responses with bounded backoff.\n\n### Error notes\n- 400 can indicate an invalid status enum, negative skip, excessive skip, invalid take, or overlong search term.\n- 403 means the key cannot read Insurance Discovery for the selected tenant.\n- 429 should be retried with backoff rather than tight polling.\n","tags":["Insurance Discovery"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["DISC_PENDING","DISC_SEARCHING","DISC_FOUND","DISC_NOT_FOUND","DISC_VERIFIED","DISC_FAILED","DISC_EXPIRED","DISC_DISMISSED"]},"required":false,"name":"status","in":"query","description":"Optional local discovery workflow status filter."},{"schema":{"type":"string","minLength":1},"required":false,"name":"batchId","in":"query","description":"Optional non-empty batch identifier filter. The batch must belong to the API key organization."},{"schema":{"type":"string","minLength":1},"required":false,"name":"patientId","in":"query","description":"Optional non-empty QuickRCM patient identifier filter. The patient must belong to the API key organization."},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"searchTerm","in":"query","description":"Optional text filter, trimmed and capped at 200 characters. Avoid logging raw values because they can include patient or payer context."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"skip","in":"query","description":"Zero-based number of search rows to skip. Defaults to 0 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"take","in":"query","description":"Maximum search rows to return. Defaults to 25 and cannot exceed 100."}],"responses":{"200":{"description":"Discovery searches for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"searches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"batchId":{"type":["string","null"]},"status":{"type":"string","enum":["DISC_PENDING","DISC_SEARCHING","DISC_FOUND","DISC_NOT_FOUND","DISC_VERIFIED","DISC_FAILED","DISC_EXPIRED","DISC_DISMISSED"]},"source":{"type":["string","null"],"enum":["DISC_SRC_EXPERIAN","DISC_SRC_CHANGE_HEALTHCARE","DISC_SRC_TRANSUNION","DISC_SRC_MANUAL"]},"trigger":{"type":"string","enum":["DISC_TRIG_REGISTRATION","DISC_TRIG_SELF_PAY_FLAG","DISC_TRIG_BATCH_RETROACTIVE","DISC_TRIG_MANUAL","DISC_TRIG_SCHEDULING"]},"foundCoverage":{"type":"object","properties":{"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"groupId":{"type":["string","null"]},"planType":{"type":["string","null"]},"coverageStart":{"type":["string","null"],"format":"date-time"},"coverageEnd":{"type":["string","null"],"format":"date-time"},"matchScore":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["payerName","memberId","groupId","planType","coverageStart","coverageEnd","matchScore"]},"eligibilityCheckId":{"type":["string","null"]},"patientInsuranceId":{"type":["string","null"]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"dismissReason":{"type":["string","null"]},"searchStartedAt":{"type":["string","null"],"format":"date-time"},"searchCompletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","batchId","status","source","trigger","foundCoverage","eligibilityCheckId","patientInsuranceId","verifiedAt","dismissedAt","dismissReason","searchStartedAt","searchCompletedAt","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["searches","total","skip","take"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"searches":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","batchId":"00000000-0000-4000-8000-000000000001","status":"DISC_PENDING","source":"DISC_SRC_EXPERIAN","trigger":"DISC_TRIG_REGISTRATION","foundCoverage":{"payerName":"Example insurance_discovery_searche","memberId":"W123456789","groupId":"00000000-0000-4000-8000-000000000001","planType":"example-plantype","coverageStart":"2026-06-08T10:15:30Z","coverageEnd":"2026-06-08T10:15:30Z","matchScore":"example-matchscore"},"eligibilityCheckId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","verifiedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","dismissReason":"example-dismissreason","searchStartedAt":"2026-06-08T10:15:30Z","searchCompletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"skip":1,"take":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"runInsuranceDiscoverySearch","summary":"Run insurance discovery search","description":"Creates and runs a single insurance discovery search for a patient in the authenticated organization.\n\n### When to use\nUse this when a patient is self-pay, uninsured, missing coverage, or otherwise requires hidden coverage discovery before downstream eligibility, claims, or patient-account workflows.\n\n### Before calling\nResolve `patientId` from the same QuickRCM tenant. Prepare required search names and trigger. Include date of birth, address, ZIP code, or SSN last four only when permitted and needed for matching. Confirm the organization has enough discovery credits.\n\n### Request guidance\n`patientId`, `trigger`, `searchFirstName`, and `searchLastName` are required by the body schema. `patientId` must be a non-empty string. `trigger` must be one of the public trigger enum values. `searchFirstName` and `searchLastName` are trimmed, must be non-empty, and are capped at 100 characters each. `searchDob` is optional but, when supplied, must be a valid calendar date in `YYYY-MM-DD` format. `searchSsnLast4` is optional but must be exactly four digits. `searchAddress` is optional, trimmed, and capped at 500 characters. `searchZipCode` is optional and must be either five digits or ZIP+4 format. Do not include `organizationId` in the body.\n\n### Request notes\n- `trigger` accepts `DISC_TRIG_REGISTRATION`, `DISC_TRIG_SELF_PAY_FLAG`, `DISC_TRIG_BATCH_RETROACTIVE`, `DISC_TRIG_MANUAL`, and `DISC_TRIG_SCHEDULING`.\n- The OpenAPI schema does not expose a public `simulateOnly` flag for this endpoint.\n- Optional demographic fields can improve matching but increase privacy sensitivity.\n- The request body should not include the patient's full SSN, raw EHR response, raw payer payload, or credentials.\n\n### Response semantics\nHTTP 201 returns the created or completed local search record and `meta.organizationId`. A result with found coverage still needs review and may need eligibility re-verification before billing workflows rely on it. This endpoint is not marked `SIMULATED_ONLY` in the public response schema.\n\n### Response notes\n- `status` describes local discovery workflow state, not eligibility verification.\n- `source` is nullable and, when present, identifies the discovery source enum.\n- `foundCoverage.memberId` and related coverage fields are local discovery output and should be handled as sensitive insurance data.\n- `meta.organizationId` is tenant context metadata returned by the service.\n\n### Errors and retries\n402 means the organization lacks enough discovery credits. 404 can indicate the patient was not found in the authenticated organization. 409 means a recent discovery search already exists for the patient, reflecting the 30-day dedupe behavior described by the implementation and module docs. Avoid blind retries after timeouts because the workflow can create a local record and consume credits.\n\n### Error notes\n- 400 can indicate missing required fields, invalid trigger, invalid date, overlong name/address values, invalid SSN last four, or invalid ZIP code.\n- 402 is credit exhaustion.\n- 409 is recent-search conflict/deduplication.\n- Do not retry unchanged 400 validation failures.\n","tags":["Insurance Discovery"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"Required non-empty QuickRCM patient identifier. The patient must belong to the API key organization."},"trigger":{"type":"string","enum":["DISC_TRIG_REGISTRATION","DISC_TRIG_SELF_PAY_FLAG","DISC_TRIG_BATCH_RETROACTIVE","DISC_TRIG_MANUAL","DISC_TRIG_SCHEDULING"],"description":"Required reason for the discovery search. Must be one of the public trigger enum values."},"searchFirstName":{"type":"string","minLength":1,"maxLength":100,"description":"Required first name used for discovery matching. Trimmed, non-empty, max 100 characters. Keep examples synthetic."},"searchLastName":{"type":"string","minLength":1,"maxLength":100,"description":"Required last name used for discovery matching. Trimmed, non-empty, max 100 characters. Keep examples synthetic."},"searchDob":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Optional date of birth used for matching. Must be a valid `YYYY-MM-DD` calendar date when supplied."},"searchSsnLast4":{"type":"string","pattern":"^\\d{4}$","description":"Optional last four digits of the Social Security number (SSN) used for matching. Must be exactly four digits and must not be logged."},"searchAddress":{"type":"string","minLength":1,"maxLength":500,"description":"Optional address text used for matching. Trimmed, max 500 characters, and treated as patient demographic data."},"searchZipCode":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","description":"Optional five-digit or ZIP+4 postal code used for matching."}},"required":["patientId","trigger","searchFirstName","searchLastName"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","trigger":"DISC_TRIG_REGISTRATION","searchFirstName":"Example insurance_discovery_search","searchLastName":"Example insurance_discovery_search","searchDob":"1984-03-22","searchSsnLast4":"example-searchssnlast4","searchAddress":"example-searchaddress","searchZipCode":"example-searchzipcode"}}},"description":"`patientId`, `trigger`, `searchFirstName`, and `searchLastName` are required by the body schema. `patientId` must be a non-empty string. `trigger` must be one of the public trigger enum values. `searchFirstName` and `searchLastName` are trimmed, must be non-empty, and are capped at 100 characters each. `searchDob` is optional but, when supplied, must be a valid calendar date in `YYYY-MM-DD` format. `searchSsnLast4` is optional but must be exactly four digits. `searchAddress` is optional, trimmed, and capped at 500 characters. `searchZipCode` is optional and must be either five digits or ZIP+4 format. Do not include `organizationId` in the body."},"responses":{"201":{"description":"Discovery search completed or queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"batchId":{"type":["string","null"]},"status":{"type":"string","enum":["DISC_PENDING","DISC_SEARCHING","DISC_FOUND","DISC_NOT_FOUND","DISC_VERIFIED","DISC_FAILED","DISC_EXPIRED","DISC_DISMISSED"]},"source":{"type":["string","null"],"enum":["DISC_SRC_EXPERIAN","DISC_SRC_CHANGE_HEALTHCARE","DISC_SRC_TRANSUNION","DISC_SRC_MANUAL"]},"trigger":{"type":"string","enum":["DISC_TRIG_REGISTRATION","DISC_TRIG_SELF_PAY_FLAG","DISC_TRIG_BATCH_RETROACTIVE","DISC_TRIG_MANUAL","DISC_TRIG_SCHEDULING"]},"foundCoverage":{"type":"object","properties":{"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"groupId":{"type":["string","null"]},"planType":{"type":["string","null"]},"coverageStart":{"type":["string","null"],"format":"date-time"},"coverageEnd":{"type":["string","null"],"format":"date-time"},"matchScore":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["payerName","memberId","groupId","planType","coverageStart","coverageEnd","matchScore"]},"eligibilityCheckId":{"type":["string","null"]},"patientInsuranceId":{"type":["string","null"]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"dismissReason":{"type":["string","null"]},"searchStartedAt":{"type":["string","null"],"format":"date-time"},"searchCompletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","batchId","status","source","trigger","foundCoverage","eligibilityCheckId","patientInsuranceId","verifiedAt","dismissedAt","dismissReason","searchStartedAt","searchCompletedAt","createdAt","updatedAt"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","batchId":"00000000-0000-4000-8000-000000000001","status":"DISC_PENDING","source":"DISC_SRC_EXPERIAN","trigger":"DISC_TRIG_REGISTRATION","foundCoverage":{"payerName":"Example insurance_discovery_search","memberId":"W123456789","groupId":"00000000-0000-4000-8000-000000000001","planType":"example-plantype","coverageStart":"2026-06-08T10:15:30Z","coverageEnd":"2026-06-08T10:15:30Z","matchScore":"example-matchscore"},"eligibilityCheckId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","verifiedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","dismissReason":"example-dismissreason","searchStartedAt":"2026-06-08T10:15:30Z","searchCompletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"The organization does not have enough discovery credits.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Patient not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"A recent discovery search already exists for the patient.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/insurance-discovery/searches/{searchId}":{"get":{"operationId":"getInsuranceDiscoverySearch","summary":"Get insurance discovery search","description":"Returns one local insurance discovery search when it belongs to the organization selected by the bearer API key.\n\n### When to use\nUse this after listing searches, creating a search, receiving a batch response, or before verify, dismiss, or retry actions that depend on the current search status.\n\n### Before calling\nUse a `searchId` obtained from a trusted QuickRCM response in the same tenant. Do not guess identifiers across organizations.\n\n### Request guidance\nPass non-empty `searchId` in the path. No request body is declared. Do not include organization selectors, credentials, raw vendor payloads, or patient demographics in the request.\n\n### Request notes\n- `searchId` is the only path selector.\n- The API key selects tenant context.\n- No request body is declared.\n\n### Response semantics\nHTTP 200 returns the local discovery search detail and `meta.organizationId`. It can include discovered coverage summary fields, lifecycle timestamps, and local linkage identifiers. The handler looks up the search by both `id` and authenticated `organizationId`.\n\n### Response notes\n- Use `status` to decide whether verify, dismiss, or retry is appropriate.\n- `foundCoverage` fields can be null even when the object is present.\n- `patientInsuranceId` is a local linkage, not proof of active payer eligibility.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant search context unless a prior trusted response proves it should exist. Retry only transient 5xx or 429 responses, with backoff.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant searches.\n- 401 and 403 require credential or scope correction.\n","tags":["Insurance Discovery"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"searchId","in":"path","description":"Non-empty Insurance Discovery search identifier in the path. It must belong to the API key organization."}],"responses":{"200":{"description":"Discovery search detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"batchId":{"type":["string","null"]},"status":{"type":"string","enum":["DISC_PENDING","DISC_SEARCHING","DISC_FOUND","DISC_NOT_FOUND","DISC_VERIFIED","DISC_FAILED","DISC_EXPIRED","DISC_DISMISSED"]},"source":{"type":["string","null"],"enum":["DISC_SRC_EXPERIAN","DISC_SRC_CHANGE_HEALTHCARE","DISC_SRC_TRANSUNION","DISC_SRC_MANUAL"]},"trigger":{"type":"string","enum":["DISC_TRIG_REGISTRATION","DISC_TRIG_SELF_PAY_FLAG","DISC_TRIG_BATCH_RETROACTIVE","DISC_TRIG_MANUAL","DISC_TRIG_SCHEDULING"]},"foundCoverage":{"type":"object","properties":{"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"groupId":{"type":["string","null"]},"planType":{"type":["string","null"]},"coverageStart":{"type":["string","null"],"format":"date-time"},"coverageEnd":{"type":["string","null"],"format":"date-time"},"matchScore":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["payerName","memberId","groupId","planType","coverageStart","coverageEnd","matchScore"]},"eligibilityCheckId":{"type":["string","null"]},"patientInsuranceId":{"type":["string","null"]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"dismissReason":{"type":["string","null"]},"searchStartedAt":{"type":["string","null"],"format":"date-time"},"searchCompletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","batchId","status","source","trigger","foundCoverage","eligibilityCheckId","patientInsuranceId","verifiedAt","dismissedAt","dismissReason","searchStartedAt","searchCompletedAt","createdAt","updatedAt"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","batchId":"00000000-0000-4000-8000-000000000001","status":"DISC_PENDING","source":"DISC_SRC_EXPERIAN","trigger":"DISC_TRIG_REGISTRATION","foundCoverage":{"payerName":"Example insurance_discovery_search","memberId":"W123456789","groupId":"00000000-0000-4000-8000-000000000001","planType":"example-plantype","coverageStart":"2026-06-08T10:15:30Z","coverageEnd":"2026-06-08T10:15:30Z","matchScore":"example-matchscore"},"eligibilityCheckId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","verifiedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","dismissReason":"example-dismissreason","searchStartedAt":"2026-06-08T10:15:30Z","searchCompletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Discovery search not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/insurance-discovery/searches/{searchId}/dismiss":{"put":{"operationId":"dismissInsuranceDiscoverySearch","summary":"Dismiss discovered coverage","description":"Marks a found discovery result as dismissed inside the authenticated organization.\n\n### When to use\nUse this when staff review determines that discovered coverage should not be linked or used, such as a likely false positive, stale coverage, or unrelated payer result.\n\n### Before calling\nRetrieve the search and confirm it belongs to the tenant and is in a found state appropriate for dismissal. Prepare an optional concise `dismissReason` for audit context.\n\n### Request guidance\nPass non-empty `searchId` in the path. `dismissReason` is optional in the body, but when supplied it is trimmed and must be 1 to 1000 characters. Keep it operational and PHI-minimal; do not paste vendor payloads, EHR responses, credentials, or raw payer data.\n\n### Request notes\n- `searchId` is the path selector.\n- `dismissReason` is optional but capped at 1000 characters.\n- Existing module docs state only `DISC_FOUND` searches can be dismissed in current operations.\n\n### Response semantics\nHTTP 200 returns the updated local discovery search with dismissal fields populated. It does not notify a payer, update EHR coverage, reverse a claim, or adjudicate patient financial responsibility.\n\n### Response notes\n- `status` should reflect dismissed local workflow state after success.\n- `dismissedAt` records the local dismissal timestamp.\n- `foundCoverage` may remain present for audit context, so treat the response as sensitive.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant search context. If a timeout occurs, re-read the search before retrying because dismissal is a state transition.\n\n### Error notes\n- 400 can indicate an invalid body or invalid workflow transition.\n- 404 can indicate the search is unavailable in the API key organization.\n- Do not retry state transitions blindly after client timeouts.\n","tags":["Insurance Discovery"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"searchId","in":"path","description":"Non-empty Insurance Discovery search identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dismissReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional operator-facing reason for dismissing discovered coverage. Trimmed, 1 to 1000 characters when supplied, sanitized, and free of raw vendor payloads."}}},"example":{"dismissReason":"example-dismissreason"}}},"description":"Pass non-empty `searchId` in the path. `dismissReason` is optional in the body, but when supplied it is trimmed and must be 1 to 1000 characters. Keep it operational and PHI-minimal; do not paste vendor payloads, EHR responses, credentials, or raw payer data."},"responses":{"200":{"description":"Dismissed discovery search.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"batchId":{"type":["string","null"]},"status":{"type":"string","enum":["DISC_PENDING","DISC_SEARCHING","DISC_FOUND","DISC_NOT_FOUND","DISC_VERIFIED","DISC_FAILED","DISC_EXPIRED","DISC_DISMISSED"]},"source":{"type":["string","null"],"enum":["DISC_SRC_EXPERIAN","DISC_SRC_CHANGE_HEALTHCARE","DISC_SRC_TRANSUNION","DISC_SRC_MANUAL"]},"trigger":{"type":"string","enum":["DISC_TRIG_REGISTRATION","DISC_TRIG_SELF_PAY_FLAG","DISC_TRIG_BATCH_RETROACTIVE","DISC_TRIG_MANUAL","DISC_TRIG_SCHEDULING"]},"foundCoverage":{"type":"object","properties":{"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"groupId":{"type":["string","null"]},"planType":{"type":["string","null"]},"coverageStart":{"type":["string","null"],"format":"date-time"},"coverageEnd":{"type":["string","null"],"format":"date-time"},"matchScore":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["payerName","memberId","groupId","planType","coverageStart","coverageEnd","matchScore"]},"eligibilityCheckId":{"type":["string","null"]},"patientInsuranceId":{"type":["string","null"]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"dismissReason":{"type":["string","null"]},"searchStartedAt":{"type":["string","null"],"format":"date-time"},"searchCompletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","batchId","status","source","trigger","foundCoverage","eligibilityCheckId","patientInsuranceId","verifiedAt","dismissedAt","dismissReason","searchStartedAt","searchCompletedAt","createdAt","updatedAt"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","batchId":"00000000-0000-4000-8000-000000000001","status":"DISC_PENDING","source":"DISC_SRC_EXPERIAN","trigger":"DISC_TRIG_REGISTRATION","foundCoverage":{"payerName":"Example dismiss_insurance_discovery_search","memberId":"W123456789","groupId":"00000000-0000-4000-8000-000000000001","planType":"example-plantype","coverageStart":"2026-06-08T10:15:30Z","coverageEnd":"2026-06-08T10:15:30Z","matchScore":"example-matchscore"},"eligibilityCheckId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","verifiedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","dismissReason":"example-dismissreason","searchStartedAt":"2026-06-08T10:15:30Z","searchCompletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Discovery search not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/insurance-discovery/batches":{"post":{"operationId":"startInsuranceDiscoveryBatch","summary":"Start batch insurance discovery","description":"Starts a simulated batch insurance discovery workflow for unique patients in the authenticated organization.\n\n### When to use\nUse this for controlled batch discovery previews across a set of known QuickRCM patients, especially retroactive self-pay review workflows that need a local batch record and per-patient search records.\n\n### Before calling\nResolve every `patientIds` entry from the same tenant. Remove duplicates before calling. Decide whether `filterCriteria` and an `idempotencyKey` should be stored for caller-side reconciliation. Keep all caller markers PHI-free.\n\n### Request guidance\n`patientIds` and `simulateOnly` are required. `patientIds` must contain 1 to 500 unique non-empty strings; duplicate patient IDs are rejected before batch side effects. `simulateOnly` must be true. `idempotencyKey` is optional, trimmed, 1 to 128 characters when supplied, and should not contain PHI. `filterCriteria` is an optional open object; keep it sanitized and operational.\n\n### Request notes\n- `simulateOnly` is required and must be true.\n- `patientIds` are unique QuickRCM patient identifiers in the API key organization.\n- Public docs should not imply direct live vendor execution for this endpoint.\n- `filterCriteria` can be omitted; the response field is object-or-null.\n\n### Response semantics\nHTTP 201 returns a local batch object, counts, credit fields, nullable `filterCriteria`, and `meta.smokeCategory: SIMULATED_ONLY`. The response is not a live payer coverage confirmation. The schema exposes `data.searches` as optional; document nested searches as present only when included by the implementation response, and advise callers not to depend on the field always being present.\n\n### Response notes\n- `status` is the local batch workflow status: `BATCH_PENDING`, `BATCH_IN_PROGRESS`, `BATCH_COMPLETED`, `BATCH_FAILED`, or `BATCH_CANCELLED`.\n- `creditsCharged` and `creditsRefunded` are local credit accounting fields.\n- `searches` is optional in the response schema and contains local Insurance Discovery search records only when included.\n- `meta.smokeCategory` is `SIMULATED_ONLY` for the public batch endpoint.\n\n### Errors and retries\n402 means not enough discovery credits. 404 can indicate one or more patients cannot be resolved in the tenant. Duplicate patient IDs are rejected before batch, credit, search, or vendor side effects. After timeout, list/search by stored workflow context before starting another batch because public idempotent replay semantics are not documented.\n\n### Error notes\n- 400 can indicate invalid body shape, duplicate patient IDs, too many patients, or missing/false `simulateOnly`.\n- 402 means insufficient discovery credits.\n- 404 means a patient was not found in the authenticated organization.\n","tags":["Insurance Discovery"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":500,"description":"Required array of 1 to 500 unique non-empty QuickRCM patient identifiers in the API key organization."},"filterCriteria":{"type":"object","additionalProperties":{},"description":"Optional open object stored with the batch. Response value can be an object or null. Keep values sanitized and avoid patient names, raw vendor payloads, or credentials."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller-supplied marker, trimmed and capped at 128 characters. Stored in filter criteria for reconciliation, but full server-side replay semantics are not documented."},"simulateOnly":{"type":"boolean","enum":[true],"description":"Required literal true safety flag for this public batch endpoint."}},"required":["patientIds","simulateOnly"]},"example":{"patientIds":["example-patientids"],"simulateOnly":true,"filterCriteria":{},"idempotencyKey":"example-idempotencykey"}}},"description":"`patientIds` and `simulateOnly` are required. `patientIds` must contain 1 to 500 unique non-empty strings; duplicate patient IDs are rejected before batch side effects. `simulateOnly` must be true. `idempotencyKey` is optional, trimmed, 1 to 128 characters when supplied, and should not contain PHI. `filterCriteria` is an optional open object; keep it sanitized and operational."},"responses":{"201":{"description":"Simulated batch discovery result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["BATCH_PENDING","BATCH_IN_PROGRESS","BATCH_COMPLETED","BATCH_FAILED","BATCH_CANCELLED"]},"filterCriteria":{"type":["object","null"],"additionalProperties":{}},"totalPatients":{"type":"integer","minimum":0},"searchedCount":{"type":"integer","minimum":0},"foundCount":{"type":"integer","minimum":0},"notFoundCount":{"type":"integer","minimum":0},"errorCount":{"type":"integer","minimum":0},"convertedBalance":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"creditsCharged":{"type":"integer","minimum":0},"creditsRefunded":{"type":"integer","minimum":0},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"searches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"batchId":{"type":["string","null"]},"status":{"type":"string","enum":["DISC_PENDING","DISC_SEARCHING","DISC_FOUND","DISC_NOT_FOUND","DISC_VERIFIED","DISC_FAILED","DISC_EXPIRED","DISC_DISMISSED"]},"source":{"type":["string","null"],"enum":["DISC_SRC_EXPERIAN","DISC_SRC_CHANGE_HEALTHCARE","DISC_SRC_TRANSUNION","DISC_SRC_MANUAL"]},"trigger":{"type":"string","enum":["DISC_TRIG_REGISTRATION","DISC_TRIG_SELF_PAY_FLAG","DISC_TRIG_BATCH_RETROACTIVE","DISC_TRIG_MANUAL","DISC_TRIG_SCHEDULING"]},"foundCoverage":{"type":"object","properties":{"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"groupId":{"type":["string","null"]},"planType":{"type":["string","null"]},"coverageStart":{"type":["string","null"],"format":"date-time"},"coverageEnd":{"type":["string","null"],"format":"date-time"},"matchScore":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["payerName","memberId","groupId","planType","coverageStart","coverageEnd","matchScore"]},"eligibilityCheckId":{"type":["string","null"]},"patientInsuranceId":{"type":["string","null"]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"dismissReason":{"type":["string","null"]},"searchStartedAt":{"type":["string","null"],"format":"date-time"},"searchCompletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","batchId","status","source","trigger","foundCoverage","eligibilityCheckId","patientInsuranceId","verifiedAt","dismissedAt","dismissReason","searchStartedAt","searchCompletedAt","createdAt","updatedAt"]}}},"required":["id","organizationId","status","filterCriteria","totalPatients","searchedCount","foundCount","notFoundCount","errorCount","convertedBalance","creditsCharged","creditsRefunded","startedAt","completedAt","createdAt","updatedAt"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"smokeCategory":{"type":"string","enum":["SIMULATED_ONLY"]}},"required":["organizationId","smokeCategory"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"BATCH_PENDING","filterCriteria":{},"totalPatients":1,"searchedCount":1,"foundCount":1,"notFoundCount":1,"errorCount":1,"convertedBalance":"example-convertedbalance","creditsCharged":125.5,"creditsRefunded":1,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","searches":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","batchId":"00000000-0000-4000-8000-000000000001","status":"DISC_PENDING","source":"DISC_SRC_EXPERIAN","trigger":"DISC_TRIG_REGISTRATION","foundCoverage":{"payerName":"Example insurance_discovery_batch","memberId":"W123456789","groupId":"00000000-0000-4000-8000-000000000001","planType":"example-plantype","coverageStart":"2026-06-08T10:15:30Z","coverageEnd":"2026-06-08T10:15:30Z","matchScore":"example-matchscore"},"eligibilityCheckId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","verifiedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","dismissReason":"example-dismissreason","searchStartedAt":"2026-06-08T10:15:30Z","searchCompletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","smokeCategory":"SIMULATED_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"The organization does not have enough discovery credits.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"A patient was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/insurance-discovery/searches/{searchId}/verify":{"post":{"operationId":"verifyDiscoveredCoverage","summary":"Verify discovered coverage","description":"Verifies discovered coverage and applies local QuickRCM database updates inside the authenticated organization.\n\n### When to use\nUse this after staff or automation review determines a found discovery result should become local coverage/account context for the patient.\n\n### Before calling\nRetrieve the search, confirm it belongs to the tenant, confirm it is in a found state appropriate for verification, and make sure discovered payer/member/group/coverage details are plausible enough for local use.\n\n### Request guidance\nPass non-empty `searchId` in the path. `idempotencyKey` is optional, trimmed, 1 to 128 characters when supplied, and should be a caller retry marker only. Keep it PHI-free. The evidenced handler parses this field for request-shape compatibility but does not echo it or store it on the search. No `simulateOnly` flag is declared for verification because the OpenAPI response categorizes the endpoint as `SAFE_WRITE_DB_ONLY`.\n\n### Request notes\n- `searchId` is the path selector.\n- `idempotencyKey` is optional and capped at 128 characters.\n- `idempotencyKey` is currently parsed for request-shape compatibility and is not echoed or stored by the evidenced handler.\n- Existing module docs state only `DISC_FOUND` searches can be verified in current operations.\n\n### Response semantics\nHTTP 200 returns the updated local search record and `meta.smokeCategory: SAFE_WRITE_DB_ONLY`. Verification is a local database state change that may create a new local `PatientInsurance` record when discovered member data is available, stores that new identifier on the search, updates self-pay patient-account financial class, and updates batch converted balance when applicable. If discovered member data is unavailable, `patientInsuranceId` remains null. It is not payer eligibility verification, claim submission readiness, EHR write-back, or final coverage adjudication.\n\n### Response notes\n- `verifiedAt` records local verification time.\n- `patientInsuranceId` identifies a newly created local patient insurance record when discovered member data is available; otherwise it remains null.\n- Do not describe verification as linking to a pre-existing local insurance record unless implementation evidence changes.\n- `SAFE_WRITE_DB_ONLY` means the documented public response is local database write scope, not external coverage confirmation.\n- `meta.organizationId` is tenant context metadata returned by the service.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant search context. 400 can indicate the search is not in `DISC_FOUND`. If a timeout occurs, re-read the search and related patient insurance state before retrying because verification is a state-changing local write.\n\n### Error notes\n- 400 can indicate invalid body or invalid workflow transition.\n- 404 can indicate search not found in the API key organization.\n- Retry only after checking current local state.\n","tags":["Insurance Discovery"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"searchId","in":"path","description":"Non-empty Insurance Discovery search identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker, trimmed and capped at 128 characters. Keep it opaque and PHI-free; current evidence shows parsing only, not echoed or stored idempotent replay state."}}},"example":{"idempotencyKey":"example-idempotencykey"}}},"description":"Pass non-empty `searchId` in the path. `idempotencyKey` is optional, trimmed, 1 to 128 characters when supplied, and should be a caller retry marker only. Keep it PHI-free. The evidenced handler parses this field for request-shape compatibility but does not echo it or store it on the search. No `simulateOnly` flag is declared for verification because the OpenAPI response categorizes the endpoint as `SAFE_WRITE_DB_ONLY`."},"responses":{"200":{"description":"Verified discovery search.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"batchId":{"type":["string","null"]},"status":{"type":"string","enum":["DISC_PENDING","DISC_SEARCHING","DISC_FOUND","DISC_NOT_FOUND","DISC_VERIFIED","DISC_FAILED","DISC_EXPIRED","DISC_DISMISSED"]},"source":{"type":["string","null"],"enum":["DISC_SRC_EXPERIAN","DISC_SRC_CHANGE_HEALTHCARE","DISC_SRC_TRANSUNION","DISC_SRC_MANUAL"]},"trigger":{"type":"string","enum":["DISC_TRIG_REGISTRATION","DISC_TRIG_SELF_PAY_FLAG","DISC_TRIG_BATCH_RETROACTIVE","DISC_TRIG_MANUAL","DISC_TRIG_SCHEDULING"]},"foundCoverage":{"type":"object","properties":{"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"groupId":{"type":["string","null"]},"planType":{"type":["string","null"]},"coverageStart":{"type":["string","null"],"format":"date-time"},"coverageEnd":{"type":["string","null"],"format":"date-time"},"matchScore":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["payerName","memberId","groupId","planType","coverageStart","coverageEnd","matchScore"]},"eligibilityCheckId":{"type":["string","null"]},"patientInsuranceId":{"type":["string","null"]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"dismissReason":{"type":["string","null"]},"searchStartedAt":{"type":["string","null"],"format":"date-time"},"searchCompletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","batchId","status","source","trigger","foundCoverage","eligibilityCheckId","patientInsuranceId","verifiedAt","dismissedAt","dismissReason","searchStartedAt","searchCompletedAt","createdAt","updatedAt"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"smokeCategory":{"type":"string","enum":["SAFE_WRITE_DB_ONLY"]}},"required":["organizationId","smokeCategory"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","batchId":"00000000-0000-4000-8000-000000000001","status":"DISC_PENDING","source":"DISC_SRC_EXPERIAN","trigger":"DISC_TRIG_REGISTRATION","foundCoverage":{"payerName":"Example verify_discovered_coverage","memberId":"W123456789","groupId":"00000000-0000-4000-8000-000000000001","planType":"example-plantype","coverageStart":"2026-06-08T10:15:30Z","coverageEnd":"2026-06-08T10:15:30Z","matchScore":"example-matchscore"},"eligibilityCheckId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","verifiedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","dismissReason":"example-dismissreason","searchStartedAt":"2026-06-08T10:15:30Z","searchCompletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","smokeCategory":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Discovery search not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/insurance-discovery/searches/{searchId}/retry":{"post":{"operationId":"retryInsuranceDiscoverySearch","summary":"Retry failed insurance discovery search","description":"Retries a failed insurance discovery search in simulated mode inside the authenticated organization.\n\n### When to use\nUse this after a local search failed and the caller wants QuickRCM to run the public simulated retry workflow without documenting live vendor execution.\n\n### Before calling\nRetrieve the failed search, confirm it belongs to the tenant, confirm retry is appropriate, confirm the organization has at least 25 discovery credits for the retry, and prepare `simulateOnly: true`.\n\n### Request guidance\nPass non-empty `searchId` in the path. `simulateOnly` is required and must be true. `idempotencyKey` is optional, trimmed, 1 to 128 characters when supplied, and should be PHI-free. Do not include patient demographics in the retry request body: the current retry operation reuses the failed search's stored first name, last name, date of birth, address, and ZIP code while passing `ssnLast4: null`, so stored SSN last-four is not resubmitted.\n\n### Request notes\n- `simulateOnly` is required and must be true.\n- `searchId` is the path selector.\n- `idempotencyKey` is optional and should not include PHI.\n- The retry body intentionally contains no patient demographics.\n- Current retry behavior reuses stored first name, last name, date of birth, address, and ZIP code from the failed search, but passes `ssnLast4: null` to the discovery client.\n- Existing operations retry only searches currently in `DISC_FAILED`.\n- A retry charges the organization the standard 25 discovery credits.\n\n### Response semantics\nHTTP 200 returns the retried local search record and `meta.smokeCategory: SIMULATED_ONLY`. It can mutate local retry state and credit accounting for a 25-credit retry, but public docs should not present it as a live external vendor call or as resubmitting stored SSN last-four.\n\n### Response notes\n- `SIMULATED_ONLY` documents the public retry safety mode.\n- The returned search still requires review before verification or downstream use.\n- The response is local workflow state, not payer confirmation.\n- Do not infer that the retry response proves SSN last-four was resent; current retry evidence shows it is not resubmitted.\n\n### Errors and retries\n402 means not enough discovery credits. 404 means the search cannot be resolved in the authenticated organization. 400 can indicate the search is not failed or `simulateOnly` is missing/false. Re-read current search state after a timeout before retrying again.\n\n### Error notes\n- 400 can indicate missing or false `simulateOnly`, invalid body, or invalid workflow transition.\n- 402 is credit exhaustion.\n- Do not perform unbounded retries against failed searches.\n","tags":["Insurance Discovery"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"searchId","in":"path","description":"Non-empty Insurance Discovery search identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller-supplied marker, trimmed and capped at 128 characters. Keep it opaque and PHI-free; current evidence does not show guaranteed replay deduplication."},"simulateOnly":{"type":"boolean","enum":[true],"description":"Required literal true safety flag for public retry."}},"required":["simulateOnly"]},"example":{"simulateOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"Pass non-empty `searchId` in the path. `simulateOnly` is required and must be true. `idempotencyKey` is optional, trimmed, 1 to 128 characters when supplied, and should be PHI-free. Do not include patient demographics in the retry request body: the current retry operation reuses the failed search's stored first name, last name, date of birth, address, and ZIP code while passing `ssnLast4: null`, so stored SSN last-four is not resubmitted."},"responses":{"200":{"description":"Retried discovery search result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"batchId":{"type":["string","null"]},"status":{"type":"string","enum":["DISC_PENDING","DISC_SEARCHING","DISC_FOUND","DISC_NOT_FOUND","DISC_VERIFIED","DISC_FAILED","DISC_EXPIRED","DISC_DISMISSED"]},"source":{"type":["string","null"],"enum":["DISC_SRC_EXPERIAN","DISC_SRC_CHANGE_HEALTHCARE","DISC_SRC_TRANSUNION","DISC_SRC_MANUAL"]},"trigger":{"type":"string","enum":["DISC_TRIG_REGISTRATION","DISC_TRIG_SELF_PAY_FLAG","DISC_TRIG_BATCH_RETROACTIVE","DISC_TRIG_MANUAL","DISC_TRIG_SCHEDULING"]},"foundCoverage":{"type":"object","properties":{"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"groupId":{"type":["string","null"]},"planType":{"type":["string","null"]},"coverageStart":{"type":["string","null"],"format":"date-time"},"coverageEnd":{"type":["string","null"],"format":"date-time"},"matchScore":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["payerName","memberId","groupId","planType","coverageStart","coverageEnd","matchScore"]},"eligibilityCheckId":{"type":["string","null"]},"patientInsuranceId":{"type":["string","null"]},"verifiedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"dismissReason":{"type":["string","null"]},"searchStartedAt":{"type":["string","null"],"format":"date-time"},"searchCompletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","batchId","status","source","trigger","foundCoverage","eligibilityCheckId","patientInsuranceId","verifiedAt","dismissedAt","dismissReason","searchStartedAt","searchCompletedAt","createdAt","updatedAt"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"smokeCategory":{"type":"string","enum":["SIMULATED_ONLY"]}},"required":["organizationId","smokeCategory"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","batchId":"00000000-0000-4000-8000-000000000001","status":"DISC_PENDING","source":"DISC_SRC_EXPERIAN","trigger":"DISC_TRIG_REGISTRATION","foundCoverage":{"payerName":"Example retry_insurance_discovery_search","memberId":"W123456789","groupId":"00000000-0000-4000-8000-000000000001","planType":"example-plantype","coverageStart":"2026-06-08T10:15:30Z","coverageEnd":"2026-06-08T10:15:30Z","matchScore":"example-matchscore"},"eligibilityCheckId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","verifiedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","dismissReason":"example-dismissreason","searchStartedAt":"2026-06-08T10:15:30Z","searchCompletedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","smokeCategory":"SIMULATED_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"The organization does not have enough discovery credits.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Discovery search not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/medical-coding/jobs":{"get":{"operationId":"listMedicalCodingJobs","summary":"List medical coding jobs","description":"Lists CodingJob summaries owned by the organization selected by the bearer API key, with optional local filters for status and linked appointment, claim, or scribe job.\n\n### When to use\nUse this endpoint to build coding worklists, poll bounded local workflow state, find jobs before opening detail, or reconcile downstream workflows by QuickRCM linkage identifiers.\n\n### Before calling\nAuthenticate with `medical-coding:read`, `medical-coding:write`, `medicalCoding:read`, or `medicalCoding:write`. Choose bounded pagination and apply the narrowest useful filters.\n\n### Request guidance\n`page` is one-based, defaults to 1, and is capped at 10000. `pageSize` defaults to 25 and is capped at 100. `status` must be one of the public CodingJob status values. `appointmentId`, `claimId`, and `scribeJobId` are optional same-organization linkage filters.\n\n### Request notes\n- Do not send `organizationId`; tenant context comes from the API key.\n- Use `pageSize` no larger than 100.\n- Linkage filters are useful for reconciliation and reduce PHI-adjacent result volume.\n\n### Response semantics\nHTTP 200 returns `data.jobs`, `total`, `page`, `pageSize`, and `totalPages`. Job summaries include local workflow status, source classification, optional specialty, priority and service-level agreement (SLA) fields, linkage IDs, code preview/count, estimated reimbursement string, and timestamps. The response intentionally omits raw clinical text and raw extracted payloads.\n\n### Response notes\n- `codesPreview` is a small code/type preview, not the full coding evidence trail.\n- `source` is derived as `outpatient_billing`, `scribe`, or `manual_extract` from local job data.\n- `totalPages` is calculated from `total` and `pageSize` for the current filter set.\n\n### Errors and retries\nTreat 400 as invalid query input, 401 as missing or invalid bearer credentials, and 403 as insufficient scope or organization access. Retry transient server failures with bounded backoff rather than tight polling.\n\n### Error notes\n- 400 can indicate an unsupported status or out-of-range pagination value.\n- 403 means credential, scope, or tenant authorization needs correction.\n- Avoid logging raw query filters when they encode patient, claim, or visit context.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":10000},"required":false,"name":"page","in":"query","description":"One-based page number. Defaults to 1 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"pageSize","in":"query","description":"Maximum jobs to return per page. Defaults to 25 and cannot exceed 100."},{"schema":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"]},"required":false,"name":"status","in":"query","description":"Optional CodingJob status filter: PENDING, UPLOADED, PROCESSING, COMPLETED, PASSED, REQUIRED_CORRECTION, HUMAN_IN_LOOP, FAILED, or INVALID."},{"schema":{"type":"string","minLength":1},"required":false,"name":"appointmentId","in":"query","description":"Optional QuickRCM Appointment linkage filter scoped to the API key organization."},{"schema":{"type":"string","minLength":1},"required":false,"name":"claimId","in":"query","description":"Optional QuickRCM Claim linkage filter scoped to the API key organization."},{"schema":{"type":"string","minLength":1},"required":false,"name":"scribeJobId","in":"query","description":"Optional QuickRCM ScribeJob linkage filter scoped to the API key organization."}],"responses":{"200":{"description":"Medical coding jobs list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"]},"source":{"type":"string","enum":["outpatient_billing","scribe","manual_extract"]},"specialty":{"type":["string","null"]},"priorityScore":{"type":["integer","null"]},"priorityTier":{"type":["string","null"]},"estimatedReimbursement":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"scribeJobId":{"type":["string","null"]},"claimId":{"type":["string","null"]},"assignedToId":{"type":["string","null"]},"slaDeadline":{"type":["string","null"],"format":"date-time"},"slaStatus":{"type":["string","null"]},"codesPreview":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"type":{"type":"string","enum":["icd","cpt"]}},"required":["code","type"]}},"codesCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","status","source","specialty","priorityScore","priorityTier","estimatedReimbursement","appointmentId","scribeJobId","claimId","assignedToId","slaDeadline","slaStatus","codesPreview","codesCount","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1},"totalPages":{"type":"integer","minimum":0}},"required":["jobs","total","page","pageSize","totalPages"]}},"required":["success","data"]},"example":{"success":true,"data":{"jobs":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"PENDING","source":"outpatient_billing","specialty":"example-specialty","priorityScore":1,"priorityTier":"example-prioritytier","estimatedReimbursement":"example-estimatedreimbursement","appointmentId":"00000000-0000-4000-8000-000000000001","scribeJobId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","assignedToId":"00000000-0000-4000-8000-000000000001","slaDeadline":"2026-06-08T10:15:30Z","slaStatus":"example-slastatus","codesPreview":[{"code":"ERROR","type":"icd"}],"codesCount":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1,"totalPages":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}}}},"post":{"operationId":"createMedicalCodingJob","summary":"Create a queued medical coding job","description":"Creates an organization-scoped CodingJob from supplied medical-record text and optional same-organization linkages, then records local public API queue metadata.\n\n### When to use\nUse this when an integration has minimum necessary clinical text or a document pointer and wants QuickRCM to track a local coding job before review or later simulated processing.\n\n### Before calling\nAuthenticate with Medical Coding write scope. Resolve optional `appointmentId`, `scribeJobId`, or `claimId` from the same organization before including them.\n\n### Request guidance\n`medicalRecord` is required and must be non-empty. Keep it minimum necessary and synthetic in docs. `documentUrl` must be a URL if supplied, but this endpoint stores a pointer and does not upload file bytes. `idempotencyKey` is accepted up to 128 characters and recorded in local metadata; current evidence does not show server-side replay deduplication.\n\n### Request notes\n- `queueOnly` is accepted by the schema, but current handler behavior remains local queued metadata.\n- Optional linked records are verified by `id` plus organization.\n- Do not use `documentUrl` for signed URLs, storage keys, portal URLs with credentials, or raw vendor payloads.\n\n### Response semantics\nSuccess returns HTTP 202 with `id`, `organizationId`, local status, and `externalRiskHandling: QUEUED_ONLY`. This is local job creation and queue-style handling, not completed coding or external processing.\n\n### Response notes\n- HTTP 202 means local acceptance.\n- `externalRiskHandling: QUEUED_ONLY` is a local safety marker.\n- The submitted `medicalRecord` is stored as local CodingJob rawText but is not returned by public read responses.\n\n### Errors and retries\nFix 400 validation failures before retrying. A 404 can mean an optional linked Appointment, ScribeJob, or Claim does not belong to the authenticated organization. After a timeout, list or retrieve jobs by trusted linkage before creating another job.\n\n### Error notes\n- 404 can indicate a missing or wrong-organization linked record.\n- No server-side idempotent replay behavior is evidenced for `idempotencyKey`.\n- Treat 401/403 as credential or scope correction issues.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"medicalRecord":{"type":"string","minLength":1,"description":"Required clinical text used to create the CodingJob. Keep it minimum necessary; never log real PHI in examples or client diagnostics."},"specialty":{"type":"string","minLength":1,"description":"Optional specialty label stored on the CodingJob."},"requestedCodes":{"type":"array","items":{"type":"string","minLength":1},"description":"Optional list of requested code-system or code hints retained in public API metadata."},"appointmentId":{"type":"string","minLength":1,"description":"Optional same-organization Appointment linkage."},"scribeJobId":{"type":"string","minLength":1,"description":"Optional same-organization ScribeJob linkage."},"claimId":{"type":"string","minLength":1,"description":"Optional same-organization Claim linkage."},"documentUrl":{"type":"string","format":"uri","description":"Optional URL pointer stored on the job. This endpoint does not upload bytes."},"queueOnly":{"type":"boolean","description":"Optional schema flag. Current public behavior remains queued/local."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker, 1 to 128 characters, recorded in local metadata without evidenced replay deduplication."}},"required":["medicalRecord"]},"example":{"medicalRecord":"example-medicalrecord","specialty":"example-specialty","requestedCodes":["example-requestedcodes"],"appointmentId":"00000000-0000-4000-8000-000000000001","scribeJobId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","documentUrl":"https://example.quickintell.com/resource","queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`medicalRecord` is required and must be non-empty. Keep it minimum necessary and synthetic in docs. `documentUrl` must be a URL if supplied, but this endpoint stores a pointer and does not upload file bytes. `idempotencyKey` is accepted up to 128 characters and recorded in local metadata; current evidence does not show server-side replay deduplication."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/jobs/{codingJobId}":{"get":{"operationId":"getMedicalCodingJob","summary":"Get medical coding job","description":"Returns one organization-scoped CodingJob summary without raw clinical note text or the full extractedData payload.\n\n### When to use\nUse this after list, create, queued workflow, or another trusted QuickRCM response provides a `codingJobId` for the same tenant.\n\n### Before calling\nAuthenticate with Medical Coding read or write scope. Use only a `codingJobId` obtained in the same API-key organization context.\n\n### Request guidance\nPass `codingJobId` in the path. No request body or query parameters are declared. Do not send organization selectors, raw notes, payer data, or file URLs.\n\n### Request notes\n- `codingJobId` is the only selector.\n- Wrong-organization identifiers can be hidden as not found.\n- No query parameters are declared.\n\n### Response semantics\nHTTP 200 returns the public CodingJob summary shape. The summary contains status, source, specialty, priority/SLA values, linkage IDs, assignment, code preview/count, reimbursement estimate, and timestamps; it omits raw clinical text and raw extracted coding evidence.\n\n### Response notes\n- `data` is local CodingJob state.\n- `codesPreview` is a preview, not the complete evidence package.\n- Use write endpoints for workflow changes rather than attempting to patch returned fields directly.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant job context unless a prior trusted response proves the job should exist. Retry only transient failures or rate-limit responses with backoff.\n\n### Error notes\n- 404 means the job was not found in the authenticated organization.\n- 401/403 require credential, scope, or tenant-context correction.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"codingJobId","in":"path","description":"QuickRCM CodingJob identifier in the path. It must resolve inside the organization selected by the bearer API key."}],"responses":{"200":{"description":"Medical coding job","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"]},"source":{"type":"string","enum":["outpatient_billing","scribe","manual_extract"]},"specialty":{"type":["string","null"]},"priorityScore":{"type":["integer","null"]},"priorityTier":{"type":["string","null"]},"estimatedReimbursement":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"scribeJobId":{"type":["string","null"]},"claimId":{"type":["string","null"]},"assignedToId":{"type":["string","null"]},"slaDeadline":{"type":["string","null"],"format":"date-time"},"slaStatus":{"type":["string","null"]},"codesPreview":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"type":{"type":"string","enum":["icd","cpt"]}},"required":["code","type"]}},"codesCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","status","source","specialty","priorityScore","priorityTier","estimatedReimbursement","appointmentId","scribeJobId","claimId","assignedToId","slaDeadline","slaStatus","codesPreview","codesCount","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"PENDING","source":"outpatient_billing","specialty":"example-specialty","priorityScore":1,"priorityTier":"example-prioritytier","estimatedReimbursement":"example-estimatedreimbursement","appointmentId":"00000000-0000-4000-8000-000000000001","scribeJobId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","assignedToId":"00000000-0000-4000-8000-000000000001","slaDeadline":"2026-06-08T10:15:30Z","slaStatus":"example-slastatus","codesPreview":[{"code":"ERROR","type":"icd"}],"codesCount":1,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding job not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}},"put":{"operationId":"updateMedicalCodingJob","summary":"Update a medical coding job","description":"Updates safe local workflow fields on an organization-scoped CodingJob and returns the updated public job summary.\n\n### When to use\nUse this to adjust status, specialty, priority, assignment, SLA fields, or claim linkage after an integration or staff workflow changes local job context.\n\n### Before calling\nAuthenticate with Medical Coding write scope. Verify the job belongs to the same tenant. If setting `claimId`, resolve a same-organization Claim. If setting `assignedToId`, use an active organization member.\n\n### Request guidance\nThe body must include at least one supported field. `status` must be a public CodingJob status. `priorityScore` is nullable and must be an integer from 0 through 100 when supplied. `slaDeadline` must be null or an ISO datetime. `claimId` and `assignedToId` are verified before update.\n\n### Request notes\n- `codingJobId` in the path must resolve inside the API-key organization.\n- Send only supported workflow fields.\n- `assignedToId` must be an active member of the authenticated organization.\n\n### Response semantics\nHTTP 200 returns the updated public CodingJob summary. This endpoint updates local workflow fields only; it does not run coding engines, post charges, create claims, or write back to an EHR.\n\n### Response notes\n- The response mirrors the public CodingJob summary schema.\n- Updated `status` is local workflow status.\n- No raw clinical text or extractedData is returned.\n\n### Errors and retries\nFix 400 validation failures or empty updates before retrying. Treat 404 as missing or wrong-tenant job, claim, or assignee context. After a timeout, re-read the job before retrying to avoid overwriting newer workflow edits.\n\n### Error notes\n- 400 can mean no supported fields were supplied.\n- 404 can indicate the job, claim, or assignee was not found for this organization.\n- Retry after reading current state when update requests time out.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"codingJobId","in":"path","description":"QuickRCM CodingJob identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","UPLOADED","PROCESSING","COMPLETED","PASSED","REQUIRED_CORRECTION","HUMAN_IN_LOOP","FAILED","INVALID"],"description":"Optional local CodingJob status."},"specialty":{"type":["string","null"],"minLength":1,"description":"Optional nullable specialty label."},"priorityScore":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Optional nullable integer priority score from 0 through 100."},"priorityTier":{"type":["string","null"],"minLength":1,"description":"Optional nullable local priority-tier label."},"assignedToId":{"type":["string","null"],"minLength":1,"description":"Optional nullable user identifier. When non-null, the user must be an active organization member."},"slaDeadline":{"type":["string","null"],"format":"date-time","description":"Optional nullable ISO datetime used for local SLA tracking."},"slaStatus":{"type":["string","null"],"minLength":1,"description":"Optional nullable local SLA status label."},"claimId":{"type":["string","null"],"minLength":1,"description":"Optional nullable same-organization Claim linkage."}}},"example":{"status":"PENDING","specialty":"example-specialty","priorityScore":1,"priorityTier":"example-prioritytier","assignedToId":"00000000-0000-4000-8000-000000000001","slaDeadline":"2026-06-08T10:15:30Z","slaStatus":"example-slastatus","claimId":"00000000-0000-4000-8000-000000000001"}}},"description":"The body must include at least one supported field. `status` must be a public CodingJob status. `priorityScore` is nullable and must be an integer from 0 through 100 when supplied. `slaDeadline` must be null or an ISO datetime. `claimId` and `assignedToId` are verified before update."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/jobs/{codingJobId}/extract":{"post":{"operationId":"extractMedicalCodingJob","summary":"Queue or simulate coding extraction","description":"Validates or records a safe simulated extraction request for an existing organization-scoped CodingJob.\n\n### When to use\nUse this when an integration wants to mark a CodingJob for extraction-style processing while preserving public API safety boundaries.\n\n### Before calling\nAuthenticate with Medical Coding write scope and use a `codingJobId` from the same organization.\n\n### Request guidance\nSet `validateOnly: true` to check ownership and request shape without changing the job. Otherwise the handler sets the job to PROCESSING and records public API extraction metadata with `externalRiskHandling: SIMULATED_ONLY`. `idempotencyKey` is recorded as local metadata for non-validate requests; current evidence does not show replay deduplication.\n\n### Request notes\n- `codingJobId` is organization-scoped path state.\n- `validateOnly` returns without updating the job.\n- `queueOnly` is accepted by the schema but non-validate behavior remains simulated/local metadata.\n\n### Response semantics\nValidate-only returns HTTP 200 with `status: VALIDATED_ONLY`. Non-validate success returns HTTP 202 with `status: PROCESSING` and `externalRiskHandling: SIMULATED_ONLY`. Neither branch directly invokes LLM or OCR extraction or returns extracted codes.\n\n### Response notes\n- `VALIDATED_ONLY` means validation-only success.\n- `SIMULATED_ONLY` means local metadata was recorded.\n- No code set or extraction evidence is returned.\n\n### Errors and retries\nFix invalid body values before retrying. Treat 404 as missing or wrong-organization job context. For non-validate requests, re-read the job after a timeout before retrying because metadata may already have been recorded.\n\n### Error notes\n- 404 means `codingJobId` did not resolve inside the API key organization.\n- Do not treat 202 as completed coding.\n- Do not include PHI or secrets in `idempotencyKey`.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"codingJobId","in":"path","description":"QuickRCM CodingJob identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requestedCodes":{"type":"array","items":{"type":"string","minLength":1},"description":"Optional list of requested code hints retained in extraction metadata."},"validateOnly":{"type":"boolean","description":"When true, validates request shape and ownership without updating job state."},"queueOnly":{"type":"boolean","description":"Optional schema flag. Current handler still records simulated/local metadata for non-validate requests."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker, 1 to 128 characters. Recorded in non-validate metadata without evidenced replay deduplication."}}},"example":{"requestedCodes":["example-requestedcodes"],"validateOnly":true,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"Set `validateOnly: true` to check ownership and request shape without changing the job. Otherwise the handler sets the job to PROCESSING and records public API extraction metadata with `externalRiskHandling: SIMULATED_ONLY`. `idempotencyKey` is recorded as local metadata for non-validate requests; current evidence does not show replay deduplication."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/jobs/{codingJobId}/rerun":{"post":{"operationId":"rerunMedicalCodingJob","summary":"Queue or simulate coding rerun","description":"Validates or records a safe simulated rerun request for an existing organization-scoped CodingJob.\n\n### When to use\nUse this when a previously created CodingJob needs local rerun tracking after staff edits, clarification answers, or integration retry orchestration.\n\n### Before calling\nAuthenticate with Medical Coding write scope and use a `codingJobId` from the same organization.\n\n### Request guidance\nThe body shape matches extract. `validateOnly: true` returns validation-only success. Otherwise the handler sets the job to PROCESSING and records public API rerun metadata with `externalRiskHandling: SIMULATED_ONLY`. `idempotencyKey` is metadata only; no replay deduplication is evidenced.\n\n### Request notes\n- `codingJobId` is the path selector and is organization-scoped.\n- `requestedCodes` is retained in rerun metadata for non-validate requests.\n- `queueOnly` does not change the documented simulated/local behavior.\n\n### Response semantics\nValidate-only returns HTTP 200 with `status: VALIDATED_ONLY`. Non-validate success returns HTTP 202 with `status: PROCESSING` and `externalRiskHandling: SIMULATED_ONLY`. It does not directly invoke an external coding engine.\n\n### Response notes\n- 200 means validation only.\n- 202 means local rerun metadata was recorded.\n- No external coding result is returned.\n\n### Errors and retries\nFix invalid body values before retrying. Treat 404 as missing or wrong-organization job context. Re-read the job after a timeout before retrying a non-validate request.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant jobs.\n- Do not treat `SIMULATED_ONLY` as completed coding.\n- Keep `idempotencyKey` free of PHI and secrets.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"codingJobId","in":"path","description":"QuickRCM CodingJob identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requestedCodes":{"type":"array","items":{"type":"string","minLength":1},"description":"Optional list of requested code hints retained in rerun metadata."},"validateOnly":{"type":"boolean","description":"When true, validates request shape and ownership without updating job state."},"queueOnly":{"type":"boolean","description":"Optional schema flag. Current behavior remains local/simulated for non-validate requests."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker, 1 to 128 characters. Recorded in non-validate metadata without evidenced replay deduplication."}}},"example":{"requestedCodes":["example-requestedcodes"],"validateOnly":true,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"The body shape matches extract. `validateOnly: true` returns validation-only success. Otherwise the handler sets the job to PROCESSING and records public API rerun metadata with `externalRiskHandling: SIMULATED_ONLY`. `idempotencyKey` is metadata only; no replay deduplication is evidenced."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/jobs/{codingJobId}/codes/{codeId}":{"put":{"operationId":"updateMedicalCodingJobCode","summary":"Accept, reject, or update a coded item","description":"Accepts, rejects, or updates one coded item in the local extracted coding data for an organization-scoped CodingJob.\n\n### When to use\nUse this for coder-review workflows where a previously generated or stored code should be accepted, rejected, or replaced with a safe local value.\n\n### Before calling\nAuthenticate with Medical Coding write scope. Load or otherwise know `codingJobId` and `codeId` from a same-organization job and current coding output.\n\n### Request guidance\n`action` is required and must be ACCEPT, REJECT, or UPDATE. For UPDATE, `newCode` is required and the handler searches the bucket selected by `codeType` (`ICD-10`, `CPT`, or `HCPCS`). `originalText` may be used to disambiguate review keys. `preserveStatus: false` prevents accepted/rejected status carryover during UPDATE.\n\n### Request notes\n- `codingJobId` and `codeId` are path parameters and must come from the same tenant context.\n- `codeType` controls the local code bucket for UPDATE; omitted values default to the ICD-10-CM bucket behavior.\n- Do not include raw clinical source text in examples; use generic labels if `originalText` is needed.\n\n### Response semantics\nHTTP 200 returns `codingJobId`, `organizationId`, `codeId`, and the action applied. The response confirms local extractedData mutation only; it is not payer submission or final compliance attestation.\n\n### Response notes\n- `action` echoes the applied action.\n- The response does not return the full updated code set.\n- A successful UPDATE changes local extractedData only.\n\n### Errors and retries\n400 can mean UPDATE was missing `newCode`. 404 can mean the job or targeted code was not found in the selected bucket. Re-read the job after timeouts before retrying local code updates.\n\n### Error notes\n- 400 is expected when UPDATE omits `newCode`.\n- 404 can indicate missing job, wrong tenant, or missing code within the selected bucket.\n- 401/403 require credential or scope correction.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"codingJobId","in":"path","description":"QuickRCM CodingJob identifier in the path. It must belong to the API key organization."},{"schema":{"type":"string","minLength":1},"required":true,"name":"codeId","in":"path","description":"Current code identifier in the path. For UPDATE, this is the code value to find and replace in the selected bucket."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["ACCEPT","REJECT","UPDATE"],"description":"Required review action: ACCEPT, REJECT, or UPDATE."},"codeType":{"type":"string","enum":["ICD-10","CPT","HCPCS"],"description":"Optional code set for UPDATE: ICD-10, CPT, or HCPCS. It selects the local bucket to search."},"originalText":{"type":"string","description":"Optional text used to build a local review key. Keep it generic and PHI-minimal."},"newCode":{"type":"string","minLength":1,"description":"Required when action is UPDATE. New code value to store locally."},"newDescription":{"type":"string","minLength":1,"description":"Optional replacement description for UPDATE."},"preserveStatus":{"type":"boolean","description":"Optional boolean. When false, accepted/rejected review status is not carried to the replacement code."}},"required":["action"]},"example":{"action":"ACCEPT","codeType":"ICD-10","originalText":"example-originaltext","newCode":"example-newcode","newDescription":"Example medical_coding_job_code note","preserveStatus":true}}},"description":"`action` is required and must be ACCEPT, REJECT, or UPDATE. For UPDATE, `newCode` is required and the handler searches the bucket selected by `codeType` (`ICD-10`, `CPT`, or `HCPCS`). `originalText` may be used to disambiguate review keys. `preserveStatus: false` prevents accepted/rejected status carryover during UPDATE."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/jobs/import":{"post":{"operationId":"importMedicalCodingJobs","summary":"Record a simulated coding import","description":"Creates a local CodingBatchImport record for a simulated medical-coding import batch.\n\n### When to use\nUse this to record import-batch metadata for sanitized job descriptors without creating Patient, Appointment, or CodingJob rows from public payload data.\n\n### Before calling\nAuthenticate with Medical Coding write scope. Prepare a bounded `jobs` array containing sanitized import descriptors, not raw clinical payloads.\n\n### Request guidance\n`jobs` is required and must contain 1 through 500 JSON objects. `fileName` is optional. `dryRun` changes the stored batch status to `VALIDATED_ONLY`, but the handler still returns HTTP 202. `idempotencyKey` is accepted by the schema, but current handler evidence does not show it being persisted or used for replay deduplication.\n\n### Request notes\n- `jobs` items are opaque JSON descriptors to the public handler.\n- Do not include raw notes, transcripts, payer payloads, raw EDI, or credentials in `jobs`.\n- Current evidence does not show `idempotencyKey` persistence for this endpoint.\n\n### Response semantics\nHTTP 202 returns the import batch `id`, `organizationId`, status, `totalJobs`, and `externalRiskHandling: SIMULATED_ONLY`. This is local import-batch metadata only, not imported clinical processing.\n\n### Response notes\n- `id` is the local CodingBatchImport identifier.\n- `totalJobs` equals the submitted jobs array length.\n- `externalRiskHandling` remains `SIMULATED_ONLY` for the public response.\n\n### Errors and retries\nFix invalid array size or malformed body before retrying. After a timeout, inspect existing import batches if available before re-sending because idempotent replay is not evidenced.\n\n### Error notes\n- 400 can indicate an empty jobs array or more than 500 items.\n- 401/403 require credential or scope correction.\n- Do not treat 202 as evidence that each job became a CodingJob.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"description":"Optional source file display name for the import batch. Do not embed PHI in filenames."},"jobs":{"type":"array","items":{"type":"object","additionalProperties":{}},"minItems":1,"maxItems":500,"description":"Required array of 1 to 500 sanitized job descriptor objects."},"dryRun":{"type":"boolean","description":"Optional boolean. When true, the created batch status is `VALIDATED_ONLY`; the response remains HTTP 202."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker accepted by schema. Current handler evidence does not show persistence or replay deduplication."}},"required":["jobs"]},"example":{"jobs":[{}],"fileName":"Example import_medical_coding_job","dryRun":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`jobs` is required and must contain 1 through 500 JSON objects. `fileName` is optional. `dryRun` changes the stored batch status to `VALIDATED_ONLY`, but the handler still returns HTTP 202. `idempotencyKey` is accepted by the schema, but current handler evidence does not show it being persisted or used for replay deduplication."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/jobs/{codingJobId}/clarifications":{"post":{"operationId":"submitMedicalCodingClarifications","summary":"Answer clarifications or queue safe reprocess","description":"Stores clarification answers for a CodingJob or records a simulated clarification reprocess request.\n\n### When to use\nUse `ANSWER` when collecting responses to existing clarification questions. Use `REPROCESS` when the workflow should mark the job for a safe simulated reprocess after clarification handling.\n\n### Before calling\nAuthenticate with Medical Coding write scope and resolve the CodingJob in the same organization. For `ANSWER`, use question IDs from trusted QuickRCM clarification context.\n\n### Request guidance\n`action` is required and must be `ANSWER` or `REPROCESS`. `answers` is required and non-empty when `action` is `ANSWER`. For `REPROCESS`, `queueOnly` defaults to true in recorded metadata. `idempotencyKey` is recorded for REPROCESS metadata; current ANSWER branch evidence does not show idempotencyKey persistence or replay deduplication.\n\n### Request notes\n- `codingJobId` must resolve inside the API key organization.\n- Question answers can contain clinical context; examples must stay synthetic and minimum necessary.\n- `idempotencyKey` has no evidenced replay deduplication.\n\n### Response semantics\n`ANSWER` returns HTTP 200 with `clarificationStatus`, `answeredCount`, and `totalQuestions`. `REPROCESS` returns HTTP 202 with `externalRiskHandling: SIMULATED_ONLY`. Neither branch directly invokes an LLM path.\n\n### Response notes\n- `clarificationStatus` is `answered` when all known questions are answered; otherwise it is `partial`.\n- `totalQuestions` comes from existing local clarification questions and can be 0.\n- `REPROCESS` returns a simulated marker, not a completed recoding result.\n\n### Errors and retries\n400 is expected when ANSWER omits answers. Treat 404 as missing or wrong-organization CodingJob. Re-read clarification state after timeouts before retrying answer submissions.\n\n### Error notes\n- 400 means ANSWER was missing required answers or body validation failed.\n- 404 means `codingJobId` did not resolve inside the authenticated organization.\n- Do not log answer text if it contains clinical detail.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"codingJobId","in":"path","description":"QuickRCM CodingJob identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["ANSWER","REPROCESS"],"description":"Required branch selector: ANSWER stores answers; REPROCESS records simulated reprocess metadata."},"answers":{"type":"array","items":{"type":"object","properties":{"questionId":{"type":"string","minLength":1,"description":"Identifier for a clarification question already associated with the CodingJob."},"answer":{"type":"string","minLength":1,"description":"Clarification answer text. Keep examples synthetic and production payloads minimum necessary."}},"required":["questionId","answer"]},"description":"Required for ANSWER. Array of questionId/answer objects from trusted local clarification context."},"queueOnly":{"type":"boolean","description":"Optional boolean recorded for REPROCESS metadata; current behavior remains simulated/local."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker. Recorded for REPROCESS metadata; ANSWER persistence is not evidenced; no replay deduplication is evidenced."}},"required":["action"]},"example":{"action":"ANSWER","answers":[{"questionId":"00000000-0000-4000-8000-000000000001","answer":"example-answer"}],"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`action` is required and must be `ANSWER` or `REPROCESS`. `answers` is required and non-empty when `action` is `ANSWER`. For `REPROCESS`, `queueOnly` defaults to true in recorded metadata. `idempotencyKey` is recorded for REPROCESS metadata; current ANSWER branch evidence does not show idempotencyKey persistence or replay deduplication."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/jobs/{codingJobId}/claims-queue":{"post":{"operationId":"queueMedicalCodingJobClaimsHandoff","summary":"Queue coding job claims handoff","description":"Records a claims-queue handoff marker in CodingJob metadata without creating or submitting a claim.\n\n### When to use\nUse this after coding review when an integration wants local evidence that the job should be considered for later claims workflow handling.\n\n### Before calling\nAuthenticate with Medical Coding write scope and confirm the CodingJob is the intended source for later claims workflow.\n\n### Request guidance\n`queueOnly` is optional; current handler behavior is always local queue metadata. `idempotencyKey` is recorded in the handoff metadata but no server-side replay deduplication is evidenced.\n\n### Request notes\n- `codingJobId` must belong to the API key organization.\n- `queueOnly` should be documented as local workflow intent.\n- Do not include claim form payloads or raw EDI in this request.\n\n### Response semantics\nHTTP 202 returns `codingJobId`, `organizationId`, `status: QUEUED`, and `externalRiskHandling: QUEUED_ONLY`. This is a local marker only, not claim creation, claim submission, clearinghouse acknowledgment, or payer acceptance.\n\n### Response notes\n- `status: QUEUED` is a local coding metadata marker.\n- `externalRiskHandling: QUEUED_ONLY` means no immediate external submission.\n- Use Claims APIs separately for claim draft or submission workflows.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant job context. After timeouts, re-read the job metadata or downstream workflow state before retrying.\n\n### Error notes\n- 404 means the job was not found in the authenticated organization.\n- No idempotent replay response is evidenced.\n- Do not present 202 as claim acceptance.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"codingJobId","in":"path","description":"QuickRCM CodingJob identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","description":"Optional local workflow flag. Current handler records a local claimsQueueHandoff marker."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker, 1 to 128 characters, stored in local handoff metadata without evidenced replay deduplication."}}},"example":{"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`queueOnly` is optional; current handler behavior is always local queue metadata. `idempotencyKey` is recorded in the handoff metadata but no server-side replay deduplication is evidenced."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/outpatient/uploads":{"post":{"operationId":"createMedicalCodingOutpatientUpload","summary":"Create outpatient billing upload metadata","description":"Creates organization-scoped outpatient billing upload metadata from file descriptors without uploading file bytes.\n\n### When to use\nUse this when an integration has completed file storage elsewhere or wants QuickRCM to track an outpatient upload shell for later batch organization.\n\n### Before calling\nAuthenticate with Medical Coding write scope. Ensure actual file upload or storage, if any, is handled through the appropriate upload mechanism outside this route.\n\n### Request guidance\n`fileName`, `fileType`, and `fileSizeBytes` describe the file. `fileType` defaults to `application/pdf` if omitted by schema. `pageCount` is nullable. `metadata` is optional JSON and should not include PHI, signed URLs, storage keys, credentials, transcripts, or raw vendor payloads.\n\n### Request notes\n- `fileSizeBytes` must be a non-negative integer.\n- `pageCount` may be null or omitted.\n- Do not put presigned URLs, credentials, S3 keys, or real patient names in `metadata`.\n\n### Response semantics\nHTTP 201 returns local upload `id`, `organizationId`, and status such as `OBU_UPLOADED`. It confirms metadata creation only, not binary upload or OCR processing.\n\n### Response notes\n- `id` is the local OutpatientBillingUpload identifier.\n- `status: OBU_UPLOADED` is local upload metadata state.\n- No file contents are returned.\n\n### Errors and retries\nFix invalid file metadata before retrying. After a timeout, list or reconcile upload metadata if available before creating duplicates.\n\n### Error notes\n- 400 can indicate missing fileName, invalid fileSizeBytes, or invalid metadata shape.\n- 401/403 require credential or scope correction.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"description":"Required file display name. Use synthetic names in examples and avoid PHI in production filenames."},"fileType":{"type":"string","minLength":1,"default":"application/pdf","description":"Required MIME type after schema defaulting; defaults to application/pdf."},"fileSizeBytes":{"type":"integer","minimum":0,"description":"Required non-negative integer size in bytes."},"pageCount":{"type":["integer","null"],"minimum":0,"description":"Optional nullable page count."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional JSON object merged with `source: public-api` by the handler. Do not include secrets or unnecessary PHI."}},"required":["fileName","fileSizeBytes"]},"example":{"fileName":"Example medical_coding_outpatient_upload","fileSizeBytes":1,"fileType":"application/pdf","pageCount":1,"metadata":{}}}},"description":"`fileName`, `fileType`, and `fileSizeBytes` describe the file. `fileType` defaults to `application/pdf` if omitted by schema. `pageCount` is nullable. `metadata` is optional JSON and should not include PHI, signed URLs, storage keys, credentials, transcripts, or raw vendor payloads."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/outpatient/batches":{"post":{"operationId":"createMedicalCodingOutpatientBatch","summary":"Create outpatient billing batch","description":"Creates a local outpatient billing batch for one or more upload IDs already scoped to the authenticated organization.\n\n### When to use\nUse this to group outpatient upload metadata records into a local batch before review or downstream processing.\n\n### Before calling\nAuthenticate with Medical Coding write scope. Use upload IDs returned by createMedicalCodingOutpatientUpload or trusted same-organization context.\n\n### Request guidance\n`uploadIds` is required, must contain 1 through 100 identifiers, and is de-duplicated by the handler before lookup and item creation. `creditsEstimate` is optional and defaults to unique upload count multiplied by 50. `metadata` is optional JSON and should stay operational.\n\n### Request notes\n- Use upload IDs from the same organization.\n- Duplicate upload IDs collapse to unique IDs before item creation.\n- Do not include raw document text or signed URLs in `metadata`.\n\n### Response semantics\nHTTP 201 returns local batch `id`, `organizationId`, status such as `OBB_DRAFT`, and `totalItems`. It does not run OCR, LLM coding, billing validation, or claim creation.\n\n### Response notes\n- `status: OBB_DRAFT` is local batch state.\n- `totalItems` is the count of unique upload IDs used for the batch.\n- Batch creation does not process the uploaded files.\n\n### Errors and retries\n404 means one or more upload IDs were not found in the authenticated organization. Fix invalid upload IDs or metadata before retrying. After timeouts, reconcile batches before creating another one.\n\n### Error notes\n- 404 can indicate at least one upload ID is missing or wrong-tenant.\n- 400 can indicate no upload IDs or more than 100.\n- No idempotency key is declared for this endpoint.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uploadIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Required array of 1 to 100 OutpatientBillingUpload identifiers. Each must belong to the API key organization; duplicates are de-duplicated."},"creditsEstimate":{"type":"integer","minimum":0,"description":"Optional non-negative integer credit estimate. Defaults to unique upload count times 50 when omitted."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional JSON object merged with `source: public-api`; avoid PHI and secrets."}},"required":["uploadIds"]},"example":{"uploadIds":["example-uploadids"],"creditsEstimate":1,"metadata":{}}}},"description":"`uploadIds` is required, must contain 1 through 100 identifiers, and is de-duplicated by the handler before lookup and item creation. `creditsEstimate` is optional and defaults to unique upload count multiplied by 50. `metadata` is optional JSON and should stay operational."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/jobs/{codingJobId}/outpatient/checks":{"post":{"operationId":"runMedicalCodingOutpatientCheck","summary":"Run a safe outpatient billing check","description":"Validates or creates a local outpatient billing check run for an organization-scoped CodingJob without external processing.\n\n### When to use\nUse this when an integration needs local outpatient check evidence for a job before draft save or human review.\n\n### Before calling\nAuthenticate with Medical Coding write scope and resolve the CodingJob in the same organization.\n\n### Request guidance\n`dryRun: true` validates ownership and request shape and returns HTTP 200 with `VALIDATED_ONLY`. Without dryRun, the handler creates an OutpatientBillingCheckRun with engine `public-api-safe-check`, overallStatus `OBC_WARN`, and metadata including `externalRiskHandling: SAFE_WRITE_DB_ONLY`. `idempotencyKey` is metadata only; no replay deduplication is evidenced.\n\n### Request notes\n- `codingJobId` must resolve inside the API key organization.\n- `dryRun` controls whether a check run is created.\n- `idempotencyKey` is stored in check metadata for persisted runs without evidenced dedupe.\n\n### Response semantics\nDry-run returns HTTP 200 with `codingJobId`, `organizationId`, and `status: VALIDATED_ONLY`. Persisted checks return HTTP 201 with check run `id`, `organizationId`, `codingJobId`, and `overallStatus`. The response is local check state only.\n\n### Response notes\n- 200 means validation only; no check run was created.\n- 201 means a local check run row was created.\n- `overallStatus: OBC_WARN` is the current safe local default.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant CodingJob. After a timeout on a persisted check, inspect check-run history before retrying.\n\n### Error notes\n- 404 means the CodingJob was not found in the authenticated organization.\n- Do not present `OBC_WARN` as an external payer or coding-engine result.\n- Keep idempotency keys free of PHI.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"codingJobId","in":"path","description":"QuickRCM CodingJob identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"When true, validates without creating an OutpatientBillingCheckRun."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker recorded in persisted check metadata without evidenced replay deduplication."}}},"example":{"dryRun":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`dryRun: true` validates ownership and request shape and returns HTTP 200 with `VALIDATED_ONLY`. Without dryRun, the handler creates an OutpatientBillingCheckRun with engine `public-api-safe-check`, overallStatus `OBC_WARN`, and metadata including `externalRiskHandling: SAFE_WRITE_DB_ONLY`. `idempotencyKey` is metadata only; no replay deduplication is evidenced."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/jobs/{codingJobId}/outpatient/draft":{"post":{"operationId":"saveMedicalCodingOutpatientDraft","summary":"Save an outpatient billing draft","description":"Validates or saves local outpatient billing draft selections for an organization-scoped CodingJob and records a coder decision row on save.\n\n### When to use\nUse this when a coder or integration has selected local outpatient claim-draft values that should be stored without finalizing a claim.\n\n### Before calling\nAuthenticate with Medical Coding write scope. Resolve the CodingJob in the same organization and prepare sanitized `selections` JSON.\n\n### Request guidance\n`dryRun: true` validates without persistence and returns HTTP 200 with `VALIDATED_ONLY`. Without dryRun, the handler stores draft metadata on the CodingJob, writes an `OBD_DRAFT_SAVE` coder decision, and returns HTTP 200 with `draftSavedAt`. `idempotencyKey` is stored in saved draft/decision metadata; no replay deduplication is evidenced.\n\n### Request notes\n- `codingJobId` must belong to the API key organization.\n- `selections` is a generic JSON object; document only safe, non-PHI examples.\n- `dryRun` and save both use HTTP 200 but have different persistence behavior.\n\n### Response semantics\nBoth branches return HTTP 200. Dry-run returns `status: VALIDATED_ONLY`; persisted save returns `draftSavedAt`. Saving is a local draft action only and does not create, submit, or finalize a claim.\n\n### Response notes\n- `draftSavedAt` is returned only for persisted saves.\n- A saved draft marks local extractedData as draft state.\n- The endpoint does not create a Claim.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant CodingJob. After a timeout on a save request, re-read job draft state before retrying to avoid duplicate decision rows.\n\n### Error notes\n- 404 means the CodingJob did not resolve in the authenticated organization.\n- No idempotent replay response is evidenced.\n- Avoid logging `selections` if they contain clinical context.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"codingJobId","in":"path","description":"QuickRCM CodingJob identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selections":{"type":"object","additionalProperties":{},"description":"Optional JSON object with local outpatient draft selections. Keep examples synthetic and production values minimum necessary."},"dryRun":{"type":"boolean","description":"When true, validates without persisting draft selections."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker recorded in saved draft/decision metadata without evidenced replay deduplication."}}},"example":{"selections":{},"dryRun":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`dryRun: true` validates without persistence and returns HTTP 200 with `VALIDATED_ONLY`. Without dryRun, the handler stores draft metadata on the CodingJob, writes an `OBD_DRAFT_SAVE` coder decision, and returns HTTP 200 with `draftSavedAt`. `idempotencyKey` is stored in saved draft/decision metadata; no replay deduplication is evidenced."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/cdi-queries":{"post":{"operationId":"createMedicalCodingCdiQuery","summary":"Create a CDI query","description":"Creates an organization-scoped Clinical Documentation Improvement (CDI) query from public API-safe fields.\n\n### When to use\nUse this when coding review identifies a local documentation question that should be tracked for provider or internal follow-up.\n\n### Before calling\nAuthenticate with Medical Coding write scope. Resolve optional `codingJobId`, `billingEncounterId`, and `patientId` in the same organization before including them.\n\n### Request guidance\n`queryType` and `queryText` are required. Optional linkages are verified for the authenticated organization. `currentCode`, `potentialCode`, `estimatedFinancialImpact`, and `rafDelta` are optional. RAF means risk adjustment factor. Keep `queryText` minimum necessary and avoid credentials, raw notes, transcripts, or payer payloads.\n\n### Request notes\n- CDI stands for Clinical Documentation Improvement.\n- Optional linked records must belong to the API key organization.\n- `queryText` may contain clinical context; public docs must use synthetic examples.\n\n### Response semantics\nHTTP 201 returns local CDI query `id`, `organizationId`, and status `CDI_DRAFT`. It does not send the query externally or notify a provider by itself.\n\n### Response notes\n- `status: CDI_DRAFT` is local lifecycle state.\n- `id` is the local CDI query identifier for future status updates.\n- No external delivery is performed by this endpoint.\n\n### Errors and retries\n404 can indicate a linked CodingJob, BillingEncounter, or Patient was not found in the authenticated organization. After a timeout, search local CDI query state before creating a duplicate.\n\n### Error notes\n- 404 can mean a linked CodingJob, BillingEncounter, or Patient is missing or wrong-tenant.\n- 400 can indicate missing `queryType` or `queryText`.\n- No idempotency key is declared.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"codingJobId":{"type":"string","minLength":1,"description":"Optional same-organization CodingJob linkage."},"billingEncounterId":{"type":"string","minLength":1,"description":"Optional same-organization BillingEncounter linkage."},"patientId":{"type":"string","minLength":1,"description":"Optional same-organization Patient linkage."},"queryType":{"type":"string","minLength":1,"description":"Required CDI query category label."},"queryText":{"type":"string","minLength":1,"description":"Required CDI query text. Keep it minimum necessary and synthetic in examples."},"currentCode":{"type":"string","minLength":1,"description":"Optional current code value associated with the question."},"potentialCode":{"type":"string","minLength":1,"description":"Optional potential code value associated with the question."},"estimatedFinancialImpact":{"type":"number","description":"Optional numeric estimated financial impact."},"rafDelta":{"type":"number","description":"Optional numeric risk adjustment factor delta."}},"required":["queryType","queryText"]},"example":{"queryType":"example-querytype","queryText":"example-querytext","codingJobId":"00000000-0000-4000-8000-000000000001","billingEncounterId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","currentCode":"example-currentcode","potentialCode":"example-potentialcode","estimatedFinancialImpact":1.25,"rafDelta":1.25}}},"description":"`queryType` and `queryText` are required. Optional linkages are verified for the authenticated organization. `currentCode`, `potentialCode`, `estimatedFinancialImpact`, and `rafDelta` are optional. RAF means risk adjustment factor. Keep `queryText` minimum necessary and avoid credentials, raw notes, transcripts, or payer payloads."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/cdi-queries/{queryId}/status":{"put":{"operationId":"updateMedicalCodingCdiQueryStatus","summary":"Update CDI query lifecycle status","description":"Updates local lifecycle status fields for an organization-scoped Clinical Documentation Improvement (CDI) query.\n\n### When to use\nUse this to mark CDI query movement such as pending, sent, responded, resolved, escalated, or expired after local workflow events.\n\n### Before calling\nAuthenticate with Medical Coding write scope and use a CDI `queryId` from the same organization.\n\n### Request guidance\n`status` is required and must be one of the CDI lifecycle values. `responseText` is stored only for `CDI_RESPONDED` when supplied. `outcomeRealized` and `actualImpact` are applied for `CDI_RESOLVED`. `CDI_SENT`, `CDI_RESPONDED`, `CDI_RESOLVED`, and `CDI_ESCALATED` add local timestamp or escalation side effects, but the response only echoes id, organizationId, and status.\n\n### Request notes\n- `queryId` is organization-scoped path state.\n- Use synthetic responseText in docs and minimum necessary text in production.\n- No idempotency key is declared.\n\n### Response semantics\nHTTP 200 returns the CDI query id, organizationId, and requested status. This is local lifecycle state only and does not prove provider delivery, provider response authenticity, or financial realization beyond stored local fields.\n\n### Response notes\n- `status` echoes the requested CDI lifecycle status.\n- Timestamp side effects are not returned by this response shape.\n- The endpoint does not deliver messages externally.\n\n### Errors and retries\n404 means the CDI query did not resolve in the authenticated organization. Fix invalid status values before retrying. Re-read current status after timeouts before resubmitting status changes.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant CDI queries.\n- 400 can indicate unsupported status.\n- Avoid logging responseText if it contains clinical context.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"queryId","in":"path","description":"QuickRCM CDI query identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["CDI_DRAFT","CDI_PENDING","CDI_SENT","CDI_RESPONDED","CDI_RESOLVED","CDI_ESCALATED","CDI_EXPIRED"],"description":"Required CDI lifecycle status: CDI_DRAFT, CDI_PENDING, CDI_SENT, CDI_RESPONDED, CDI_RESOLVED, CDI_ESCALATED, or CDI_EXPIRED."},"responseText":{"type":"string","minLength":1,"description":"Optional response text applied when status is CDI_RESPONDED and supplied."},"outcomeRealized":{"type":"boolean","description":"Optional boolean applied when status is CDI_RESOLVED; defaults false in that branch when omitted."},"actualImpact":{"type":"number","description":"Optional numeric impact applied when status is CDI_RESOLVED; stored as null in that branch when omitted."}},"required":["status"]},"example":{"status":"CDI_DRAFT","responseText":"example-responsetext","outcomeRealized":true,"actualImpact":1.25}}},"description":"`status` is required and must be one of the CDI lifecycle values. `responseText` is stored only for `CDI_RESPONDED` when supplied. `outcomeRealized` and `actualImpact` are applied for `CDI_RESOLVED`. `CDI_SENT`, `CDI_RESPONDED`, `CDI_RESOLVED`, and `CDI_ESCALATED` add local timestamp or escalation side effects, but the response only echoes id, organizationId, and status."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/automation-rules":{"post":{"operationId":"upsertMedicalCodingAutomationRule","summary":"Create or update a coding automation rule","description":"Creates or updates an organization-scoped coding automation rule with local conditions and actions JSON.\n\n### When to use\nUse this to manage local coding automation configuration such as auto-accept, auto-route, escalation, SLA alert, or auto-billing rule records.\n\n### Before calling\nAuthenticate with Medical Coding write scope. If updating, use a `ruleId` from the same organization.\n\n### Request guidance\n`name`, `ruleType`, `conditions`, and `actions` are required. `ruleId` switches the endpoint to update mode. `description` is nullable. `priority` defaults to 0 and `isActive` defaults to true when omitted. Conditions and actions are stored as JSON and should not include secrets, credentials, raw clinical notes, or vendor payloads.\n\n### Request notes\n- `ruleId` present means update; absent means create.\n- `ruleType` must be AUTO_ACCEPT, AUTO_ROUTE, ESCALATION, SLA_ALERT, or AUTO_BILLING.\n- Conditions and actions are local configuration JSON, not executable external payloads.\n\n### Response semantics\nCreate returns HTTP 201 with `status: CREATED`. Update returns HTTP 200 with `status: UPDATED`. The endpoint changes local rule configuration only; it does not execute the rule against existing jobs in the immediate response.\n\n### Response notes\n- 201 plus `CREATED` means a new local rule record was created.\n- 200 plus `UPDATED` means an existing same-organization rule was updated.\n- The response does not include the stored conditions or actions.\n\n### Errors and retries\n404 means the supplied `ruleId` was not found in the authenticated organization. Fix invalid ruleType or missing JSON objects before retrying. After a timeout, search rules before creating another rule to avoid duplicates.\n\n### Error notes\n- 404 can indicate a wrong-organization or missing `ruleId`.\n- 400 can indicate an unsupported `ruleType` or missing required JSON.\n- No idempotency key is declared.\n- 429 can indicate the authenticated API key exceeded 60 requests in 60 seconds for the Medical Coding public API action; retry with bounded backoff.\n","tags":["Medical Coding"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ruleId":{"type":"string","minLength":1,"description":"Optional CodingAutomationRule identifier. When present, the handler updates that same-organization rule."},"name":{"type":"string","minLength":1,"description":"Required rule name. Keep it operational and PHI-minimal."},"description":{"type":["string","null"],"description":"Optional nullable rule description. Avoid secrets and unnecessary PHI."},"ruleType":{"type":"string","enum":["AUTO_ACCEPT","AUTO_ROUTE","ESCALATION","SLA_ALERT","AUTO_BILLING"],"description":"Required rule type: AUTO_ACCEPT, AUTO_ROUTE, ESCALATION, SLA_ALERT, or AUTO_BILLING."},"priority":{"type":"integer","description":"Optional integer priority. Defaults to 0."},"isActive":{"type":"boolean","description":"Optional boolean. Defaults to true."},"conditions":{"type":"object","additionalProperties":{},"description":"Required JSON object storing local rule matching conditions."},"actions":{"type":"object","additionalProperties":{},"description":"Required JSON object storing local rule actions."}},"required":["name","ruleType","conditions","actions"]},"example":{"name":"Example upsert_medical_coding_automation_rule","ruleType":"AUTO_ACCEPT","conditions":{},"actions":{},"ruleId":"00000000-0000-4000-8000-000000000001","description":"Example upsert_medical_coding_automation_rule note","priority":1,"isActive":true}}},"description":"`name`, `ruleType`, `conditions`, and `actions` are required. `ruleId` switches the endpoint to update mode. `description` is nullable. `priority` defaults to 0 and `isActive` defaults to true when omitted. Conditions and actions are stored as JSON and should not include secrets, credentials, raw clinical notes, or vendor payloads."},"responses":{"200":{"description":"Medical coding public API response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"201":{"description":"Medical coding public API resource created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"202":{"description":"Medical coding public API request queued or simulated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}}},"required":["success","data"]},"example":{"success":true,"data":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Medical coding resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}}}}},"/api/v1/medical-coding/code-systems":{"get":{"operationId":"getMedicalCodingCodeSystems","summary":"List supported medical coding code systems","description":"Returns the static list of medical coding code systems accepted by the async outpatient coding API.\n\n### When to use\nUse this to populate code-system selectors or validate user choices before creating outpatient coding requests in clients.\n\n### Before calling\nNo bearer auth is declared for this endpoint. No path, query, or body parameters are declared.\n\n### Request guidance\nCall with an empty request body. Because the endpoint is unauthenticated, examples should avoid implying tenant-specific results.\n\n### Request notes\n- No authorization header is required by the contract.\n- No organization selector is accepted.\n- No request body is declared.\n\n### Response semantics\nHTTP 200 returns `success: true` and `codeSystems`, where each item has `value`, `label`, `category`, and `description`. Categories are `US`, `International`, `Clinical`, or `Device`.\n\n### Response notes\n- `codeSystems` is a static array from the medical coding module.\n- `category` is one of US, International, Clinical, or Device.\n- The response is not tenant-specific.\n\n### Errors and retries\nOnly HTTP 200 is declared in the public contract. Retry transient transport failures with normal client backoff.\n\n### Error notes\n- The contract declares only a 200 success response.\n- Do not infer code validation or payer coverage from this static directory.\n","tags":["Medical Coding"],"responses":{"200":{"description":"Supported medical coding code systems","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"codeSystems":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"category":{"type":"string","enum":["US","International","Clinical","Device"]},"description":{"type":"string"}},"required":["value","label","category","description"]}}},"required":["success","codeSystems"]},"example":{"success":true,"codeSystems":[{"value":"example-value","label":"example-label","category":"US","description":"Example medical_coding_code_system note"}]}}}}}}},"/api/v1/oig-exclusion/checks":{"get":{"operationId":"listOigExclusionChecks","summary":"List OIG exclusion checks","description":"Returns a paginated list of OIG exclusion checks owned by the organization selected by the bearer API key, with optional filters for local status, checked-at date bounds, entity-name search text, and sort order.\n\n### When to use\nUse this endpoint to build compliance review queues, audit dashboards, provider screening history views, and follow-up lists for checks that need human review.\n\n### Before calling\nAuthenticate with a tenant-scoped bearer API key that has `oig-exclusion:read` or `oig-exclusion:write` scope. Choose narrow filters for compliance exports and use bounded pagination.\n\n### Request guidance\n`page` defaults to 1 and is capped at 10000. `pageSize` defaults to 25 and is capped at 100. `dateFrom` and `dateTo` are ISO 8601 date or date-time strings for `checkedAt`; when both are supplied, `dateFrom` must be before or equal to `dateTo`. `search` currently filters `entityName`, not NPI, `userId`, or `providerId`.\n\n### Request notes\n- `status` must be one of the documented `EXC_*` status values.\n- `search` is capped at 200 characters and is implemented as case-insensitive `entityName` contains matching.\n- `sortBy` supports `entityName`, `checkType`, `status`, and `checkedAt`; `sortOrder` is `asc` or `desc`.\n- Do not send `organizationId`; tenant selection comes from the bearer API key and is echoed in response metadata.\n\n### Response semantics\nA 200 response returns `data.checks`, `total`, `page`, `pageSize`, and `meta.organizationId`. Each check row contains local record identifiers, check type, entity name, optional NPI/user/provider links, status, structured match summaries, structured LEIE/SAM metadata, review metadata, and `checkedAt`.\n\n### Response notes\n- `data.checks` reflects local QuickRCM exclusion-check records, not proof of a current federal source-list lookup.\n- `matchSummary`, `leie`, and `sam` are structured summaries; the public schema does not expose raw LEIE rows or raw SAM.gov responses.\n- `reviewNotes` is intentionally omitted from the public check serializer; only reviewer identity and timestamp fields are returned.\n- `checkedAt` is the server timestamp for when the local check was performed or recorded; it is not a caller-supplied source-list timestamp.\n- `checks[].organizationId` and `meta.organizationId` should be treated as authenticated-tenant echoes, not request routing inputs.\n- Use `getOigExclusionCheck` for a single check by id.\n\n### Errors and retries\nTreat 400 as invalid filters, pagination, date bounds, status, or sort values. Treat 401/403 as credential, scope, or tenant-authorization issues. Back off on 429 and retry transient 5xx responses within normal client retry limits.\n\n### Error notes\n- 400 can indicate invalid status, date ordering, page, pageSize, sortBy, or sortOrder.\n- 403 means the authenticated caller cannot access the organization context or lacks an accepted scope.\n- 429 should be handled with client backoff rather than tight compliance polling.\n","tags":["OIG Exclusion"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["EXC_CLEAR","EXC_MATCH_FOUND","EXC_REVIEW_NEEDED","EXC_FALSE_POSITIVE","EXC_CONFIRMED_EXCLUDED","EXC_ERROR"]},"required":false,"name":"status","in":"query","description":"Optional filter for the local exclusion-check lifecycle status: `EXC_CLEAR`, `EXC_MATCH_FOUND`, `EXC_REVIEW_NEEDED`, `EXC_FALSE_POSITIVE`, `EXC_CONFIRMED_EXCLUDED`, or `EXC_ERROR`."},{"schema":{"type":"integer","minimum":1,"maximum":10000,"default":1},"required":false,"name":"page","in":"query","description":"One-based page number. Defaults to 1 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"Maximum number of checks to return. Defaults to 25 and cannot exceed 100."},{"schema":{"type":"string","minLength":1,"description":"ISO 8601 date or date-time lower bound for checkedAt, such as 2026-06-01.","example":"2026-06-01"},"required":false,"name":"dateFrom","in":"query","description":"Inclusive ISO 8601 lower bound for `checkedAt`."},{"schema":{"type":"string","minLength":1,"description":"ISO 8601 date or date-time upper bound for checkedAt, such as 2026-06-15T23:59:59Z. When both filters are provided, dateFrom must be before or equal to dateTo.","example":"2026-06-15T23:59:59Z"},"required":false,"name":"dateTo","in":"query","description":"Inclusive ISO 8601 upper bound for `checkedAt`. Must be after or equal to `dateFrom` when both are provided."},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"search","in":"query","description":"Optional free-text filter capped at 200 characters. Runtime search is by `entityName` only."},{"schema":{"type":"string","enum":["entityName","checkType","status","checkedAt"]},"required":false,"name":"sortBy","in":"query","description":"Optional sort field: `entityName`, `checkType`, `status`, or `checkedAt`."},{"schema":{"type":"string","enum":["asc","desc"]},"required":false,"name":"sortOrder","in":"query","description":"Optional sort direction: `asc` or `desc`."}],"responses":{"200":{"description":"OIG exclusion checks for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"checkType":{"type":"string","enum":["PROVIDER","EMPLOYEE","CONTRACTOR","VENDOR"]},"entityName":{"type":"string"},"npi":{"type":["string","null"]},"userId":{"type":["string","null"]},"providerId":{"type":["string","null"]},"status":{"type":"string","enum":["EXC_CLEAR","EXC_MATCH_FOUND","EXC_REVIEW_NEEDED","EXC_FALSE_POSITIVE","EXC_CONFIRMED_EXCLUDED","EXC_ERROR"]},"matchSummary":{"type":["object","null"],"properties":{"leieMatch":{"type":"boolean"},"samMatch":{"type":"boolean"},"matchScore":{"type":["number","null"]}},"required":["leieMatch","samMatch","matchScore"]},"leie":{"type":["object","null"],"properties":{"exclusionType":{"type":["string","null"]},"exclusionDate":{"type":["string","null"],"format":"date-time"},"reinstatementDate":{"type":["string","null"],"format":"date-time"},"state":{"type":["string","null"]},"specialty":{"type":["string","null"]}},"required":["exclusionType","exclusionDate","reinstatementDate","state","specialty"]},"sam":{"type":["object","null"],"properties":{"exclusionType":{"type":["string","null"]},"exclusionDate":{"type":["string","null"],"format":"date-time"}},"required":["exclusionType","exclusionDate"]},"reviewedBy":{"type":["string","null"]},"reviewedAt":{"type":["string","null"],"format":"date-time"},"checkedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","checkType","entityName","npi","userId","providerId","status","matchSummary","leie","sam","reviewedBy","reviewedAt","checkedAt"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1}},"required":["checks","total","page","pageSize"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"checks":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","checkType":"PROVIDER","entityName":"Example oig_exclusion_check","npi":"1234567893","userId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","status":"EXC_CLEAR","matchSummary":{"leieMatch":true,"samMatch":true,"matchScore":1.25},"leie":{"exclusionType":"example-exclusiontype","exclusionDate":"2026-06-08T10:15:30Z","reinstatementDate":"2026-06-08T10:15:30Z","state":"example-state","specialty":"example-specialty"},"sam":{"exclusionType":"example-exclusiontype","exclusionDate":"2026-06-08T10:15:30Z"},"reviewedBy":"example-reviewedby","reviewedAt":"2026-06-08T10:15:30Z","checkedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createOigExclusionCheck","summary":"Create OIG exclusion check","description":"Submits one organization-scoped provider OIG screening request and returns the sanitized local check result. The runtime can return an existing recent matching check instead of creating a new row or performing a fresh federal-source lookup.\n\n### When to use\nUse this endpoint when a provider record needs an on-demand exclusion check before credentialing, onboarding, claim release, or compliance review.\n\n### Before calling\nAuthenticate with a tenant-scoped bearer API key that has `oig-exclusion:write` scope. Collect the provider's legal display name, 10-digit NPI, and two-uppercase-letter state code from trusted organization or credentialing data. If you send `userId` or `providerId`, confirm those IDs belong to the authenticated organization before calling.\n\n### Request guidance\n`entityName`, `checkType`, `npi`, and `state` are required. The public request schema currently accepts `checkType: PROVIDER` only. `npi` must match exactly 10 digits. `state` is validated only as two uppercase letters; the public schema does not prove the value is a real state or licensing jurisdiction. Optional `userId` and `providerId` are validated before screening: `userId` must match an active `OrganizationMember` in the authenticated organization, and `providerId` must match a non-deleted `CredentialingSession` in the authenticated organization.\n\n### Request notes\n- `entityName` must be 2 to 200 characters. Prefer legal provider names over nicknames or email addresses.\n- `checkType` is constrained to `PROVIDER` in the public create schema even though response records can represent additional check types created by other workflows.\n- `userId` is accepted only when it resolves to an active `OrganizationMember` for the authenticated organization; otherwise the endpoint returns 404 before screening.\n- `providerId` is accepted only when it resolves to a non-deleted `CredentialingSession` for the authenticated organization; otherwise the endpoint returns 404 before screening.\n- Do not include date of birth, Social Security numbers, source-list records, credentials, or raw vendor payloads in this request.\n\n### Response semantics\nA successful 201 response returns `data.check` and `meta.organizationId`. The returned check can be newly created or an existing recent deduplicated check for the same organization, entity name, and NPI. The check contains local status, structured match summary, optional structured LEIE/SAM details, and review timestamps when present.\n\n### Response notes\n- `status` is the local QuickRCM check status after screening or deduplicated lookup.\n- `matchSummary` is a structured summary and may be null when no scoring detail is available; do not document it as a raw LEIE or SAM.gov payload.\n- `leie` and `sam` contain structured metadata fields such as exclusion type/date, not raw source payloads.\n- `reviewedBy` and `reviewedAt` can be null until a human resolution is recorded.\n- `data.check.organizationId` and `meta.organizationId` should match the authenticated bearer credential's organization.\n- A 201 status should be documented as the public endpoint's success status, not as proof that a new database row or fresh LEIE/SAM lookup happened.\n\n### Errors and retries\nCorrect validation errors before retrying. 404 can mean an optional linked `userId` or `providerId` was missing from the authenticated organization or was not eligible for linking. If a client times out after submission, list recent checks or search by entity name before creating another check to avoid duplicate local records.\n\n### Error notes\n- 400 can indicate a missing required field, invalid NPI pattern, invalid state-code pattern, or unsupported check type.\n- 404 can indicate a linked `userId` or `providerId` was not found in the authenticated organization under the required active/non-deleted filters.\n- 401/403 require credential, scope, permission, or tenant-context correction.\n- 429 should be retried with backoff.\n","tags":["OIG Exclusion"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entityName":{"type":"string","minLength":2,"maxLength":200,"example":"Dr. Avery Smith","description":"Screened provider name, 2 to 200 characters. Prefer legal names and avoid email-only names."},"checkType":{"type":"string","enum":["PROVIDER"],"description":"Manual public check type. The public create schema currently allows only `PROVIDER`."},"npi":{"type":"string","pattern":"^\\d{10}$","description":"Provider National Provider Identifier value. The public schema enforces exactly 10 digits."},"state":{"type":"string","pattern":"^[A-Z]{2}$","example":"CA","description":"Two-uppercase-letter state code used as screening context. The schema enforces the pattern, not jurisdiction validity."},"userId":{"type":"string","minLength":1,"description":"Optional QuickRCM user identifier. It must resolve to an active organization member in the authenticated organization."},"providerId":{"type":"string","minLength":1,"description":"Optional QuickRCM credentialing-session/provider link. It must resolve to a non-deleted credentialing session in the authenticated organization."}},"required":["entityName","checkType","npi","state"]},"example":{"entityName":"Dr. Avery Smith","checkType":"PROVIDER","npi":"1234567893","state":"CA","userId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001"}}},"description":"`entityName`, `checkType`, `npi`, and `state` are required. The public request schema currently accepts `checkType: PROVIDER` only. `npi` must match exactly 10 digits. `state` is validated only as two uppercase letters; the public schema does not prove the value is a real state or licensing jurisdiction. Optional `userId` and `providerId` are validated before screening: `userId` must match an active `OrganizationMember` in the authenticated organization, and `providerId` must match a non-deleted `CredentialingSession` in the authenticated organization."},"responses":{"201":{"description":"Created OIG exclusion check result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"check":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"checkType":{"type":"string","enum":["PROVIDER","EMPLOYEE","CONTRACTOR","VENDOR"]},"entityName":{"type":"string"},"npi":{"type":["string","null"]},"userId":{"type":["string","null"]},"providerId":{"type":["string","null"]},"status":{"type":"string","enum":["EXC_CLEAR","EXC_MATCH_FOUND","EXC_REVIEW_NEEDED","EXC_FALSE_POSITIVE","EXC_CONFIRMED_EXCLUDED","EXC_ERROR"]},"matchSummary":{"type":["object","null"],"properties":{"leieMatch":{"type":"boolean"},"samMatch":{"type":"boolean"},"matchScore":{"type":["number","null"]}},"required":["leieMatch","samMatch","matchScore"]},"leie":{"type":["object","null"],"properties":{"exclusionType":{"type":["string","null"]},"exclusionDate":{"type":["string","null"],"format":"date-time"},"reinstatementDate":{"type":["string","null"],"format":"date-time"},"state":{"type":["string","null"]},"specialty":{"type":["string","null"]}},"required":["exclusionType","exclusionDate","reinstatementDate","state","specialty"]},"sam":{"type":["object","null"],"properties":{"exclusionType":{"type":["string","null"]},"exclusionDate":{"type":["string","null"],"format":"date-time"}},"required":["exclusionType","exclusionDate"]},"reviewedBy":{"type":["string","null"]},"reviewedAt":{"type":["string","null"],"format":"date-time"},"checkedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","checkType","entityName","npi","userId","providerId","status","matchSummary","leie","sam","reviewedBy","reviewedAt","checkedAt"]}},"required":["check"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"check":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","checkType":"PROVIDER","entityName":"Example oig_exclusion_check","npi":"1234567893","userId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","status":"EXC_CLEAR","matchSummary":{"leieMatch":true,"samMatch":true,"matchScore":1.25},"leie":{"exclusionType":"example-exclusiontype","exclusionDate":"2026-06-08T10:15:30Z","reinstatementDate":"2026-06-08T10:15:30Z","state":"example-state","specialty":"example-specialty"},"sam":{"exclusionType":"example-exclusiontype","exclusionDate":"2026-06-08T10:15:30Z"},"reviewedBy":"example-reviewedby","reviewedAt":"2026-06-08T10:15:30Z","checkedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/oig-exclusion/checks/{checkId}":{"get":{"operationId":"getOigExclusionCheck","summary":"Get OIG exclusion check","description":"Returns one OIG exclusion check when the check belongs to the organization selected by the bearer API key.\n\n### When to use\nUse this endpoint to open a compliance detail view, verify a check before resolution, or refresh a local check after an on-demand screening request.\n\n### Before calling\nAuthenticate with `oig-exclusion:read` or `oig-exclusion:write` scope and pass a non-empty `checkId` obtained from list, create, or another trusted same-organization workflow.\n\n### Request guidance\n`checkId` is a required path parameter. Do not use ids from another tenant or treat a 404 as proof that a check id does not exist globally.\n\n### Request notes\n- `checkId` must be non-empty.\n- The organization is inferred from the bearer credential, not from a request body field.\n- Use list filtering first when the caller only has provider name or status context.\n\n### Response semantics\nA 200 response returns `data.check` with the same sanitized check shape used by list and create responses, plus `meta.organizationId` for the authenticated tenant.\n\n### Response notes\n- The response is a local check record scoped to the authenticated organization.\n- Nullable `leie`, `sam`, `matchSummary`, `reviewedBy`, and `reviewedAt` fields may be null depending on the check status and review state.\n- `checkedAt` is the server timestamp for the local check record, while LEIE/SAM exclusion dates are source-summary dates when present.\n- `data.check.organizationId` and `meta.organizationId` should match the authenticated bearer credential's organization.\n- The schema does not expose raw source-list rows, raw external responses, or reviewer notes.\n\n### Errors and retries\nTreat 404 as not found in the authenticated organization. Do not retry 400/401/403 without correcting the path id, credentials, scope, or tenant context. Retry transient 5xx responses conservatively.\n\n### Error notes\n- 404 means no check with that id is available in the authenticated organization.\n- 403 means the caller cannot access the organization context selected by the credential or lacks an accepted scope.\n- 429 should be retried with backoff.\n","tags":["OIG Exclusion"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"checkId","in":"path","description":"Identifier of the local OIG exclusion check to retrieve. It is tenant-scoped in access behavior."}],"responses":{"200":{"description":"OIG exclusion check for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"check":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"checkType":{"type":"string","enum":["PROVIDER","EMPLOYEE","CONTRACTOR","VENDOR"]},"entityName":{"type":"string"},"npi":{"type":["string","null"]},"userId":{"type":["string","null"]},"providerId":{"type":["string","null"]},"status":{"type":"string","enum":["EXC_CLEAR","EXC_MATCH_FOUND","EXC_REVIEW_NEEDED","EXC_FALSE_POSITIVE","EXC_CONFIRMED_EXCLUDED","EXC_ERROR"]},"matchSummary":{"type":["object","null"],"properties":{"leieMatch":{"type":"boolean"},"samMatch":{"type":"boolean"},"matchScore":{"type":["number","null"]}},"required":["leieMatch","samMatch","matchScore"]},"leie":{"type":["object","null"],"properties":{"exclusionType":{"type":["string","null"]},"exclusionDate":{"type":["string","null"],"format":"date-time"},"reinstatementDate":{"type":["string","null"],"format":"date-time"},"state":{"type":["string","null"]},"specialty":{"type":["string","null"]}},"required":["exclusionType","exclusionDate","reinstatementDate","state","specialty"]},"sam":{"type":["object","null"],"properties":{"exclusionType":{"type":["string","null"]},"exclusionDate":{"type":["string","null"],"format":"date-time"}},"required":["exclusionType","exclusionDate"]},"reviewedBy":{"type":["string","null"]},"reviewedAt":{"type":["string","null"],"format":"date-time"},"checkedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","checkType","entityName","npi","userId","providerId","status","matchSummary","leie","sam","reviewedBy","reviewedAt","checkedAt"]}},"required":["check"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"check":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","checkType":"PROVIDER","entityName":"Example oig_exclusion_check","npi":"1234567893","userId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","status":"EXC_CLEAR","matchSummary":{"leieMatch":true,"samMatch":true,"matchScore":1.25},"leie":{"exclusionType":"example-exclusiontype","exclusionDate":"2026-06-08T10:15:30Z","reinstatementDate":"2026-06-08T10:15:30Z","state":"example-state","specialty":"example-specialty"},"sam":{"exclusionType":"example-exclusiontype","exclusionDate":"2026-06-08T10:15:30Z"},"reviewedBy":"example-reviewedby","reviewedAt":"2026-06-08T10:15:30Z","checkedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"OIG exclusion check not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/oig-exclusion/checks/bulk":{"post":{"operationId":"runOrganizationExclusionCheck","summary":"Simulate organization-wide OIG exclusion check","description":"Returns an organization-scoped dry-run summary for screenable employees and providers, including latest run metadata, without calling LEIE or SAM.gov sources.\n\n### When to use\nUse this endpoint to estimate screening scope, display compliance coverage counts, or check latest organization run metadata before using internal scheduled or manual screening workflows.\n\n### Before calling\nAuthenticate with `oig-exclusion:write` scope. Send `dryRun: true`; public callers should not use this endpoint to start live bulk federal-source screening.\n\n### Request guidance\n`scope` can be `EMPLOYEES`, `PROVIDERS`, or `ALL` and defaults to `ALL`. `dryRun` defaults to true and must remain true for the public bulk endpoint. Runtime count semantics are implementation-specific: employee count uses active `OrganizationMember` rows for the authenticated organization, and provider count uses non-deleted `CredentialingSession` rows for the authenticated organization.\n\n### Request notes\n- This endpoint is simulation-only; document `dryRun=true` as required for public callers.\n- `scope=ALL` estimates both employee and provider screening counts.\n- `scope=EMPLOYEES` returns provider count as 0; `scope=PROVIDERS` returns employee count as 0.\n- Do not describe this endpoint as creating OIG exclusion checks or making external LEIE/SAM.gov calls.\n\n### Response semantics\nA 200 response returns `data.status: SIMULATED_ONLY`, the requested scope, `dryRun: true`, employee/provider/screenable counts, nullable `latestRun`, and `meta.organizationId`. `latestRun` contains run id, organization id, run date, completion timestamp, total checked, clear count, match count, error count, and next run date when available.\n\n### Response notes\n- `status` is documented as `SIMULATED_ONLY` for the public endpoint.\n- `latestRun` can be null when no prior organization run metadata is available.\n- `employeeCount`, `providerCount`, and `estimatedScreenableCount` are counts, not matched-exclusion totals.\n- `estimatedScreenableCount` is the sum of the employee and provider counts returned for the selected scope.\n- `meta.organizationId` identifies the authenticated organization used for count queries and latest-run lookup.\n\n### Errors and retries\nCorrect invalid scope or dry-run body values before retrying. Back off on 429. Retry transient 5xx responses only within normal operational limits because this endpoint is intended for summary views, not tight polling.\n\n### Error notes\n- 400 can indicate an unsupported scope or `dryRun: false`.\n- 401/403 require credential, scope, or tenant authorization correction.\n- 429 means the caller should slow summary polling.\n","tags":["OIG Exclusion"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["EMPLOYEES","PROVIDERS","ALL"],"default":"ALL","description":"Screening population to simulate: `EMPLOYEES`, `PROVIDERS`, or `ALL`. Defaults to `ALL`."},"dryRun":{"type":"boolean","default":true,"description":"Boolean flag required to remain true. The public endpoint only simulates organization-wide screening."}}},"example":{"scope":"ALL","dryRun":true}}},"description":"`scope` can be `EMPLOYEES`, `PROVIDERS`, or `ALL` and defaults to `ALL`. `dryRun` defaults to true and must remain true for the public bulk endpoint. Runtime count semantics are implementation-specific: employee count uses active `OrganizationMember` rows for the authenticated organization, and provider count uses non-deleted `CredentialingSession` rows for the authenticated organization."},"responses":{"200":{"description":"Simulated organization-wide exclusion screening summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["SIMULATED_ONLY"]},"scope":{"type":"string","enum":["EMPLOYEES","PROVIDERS","ALL"]},"dryRun":{"type":"boolean","enum":[true]},"employeeCount":{"type":"integer","minimum":0},"providerCount":{"type":"integer","minimum":0},"estimatedScreenableCount":{"type":"integer","minimum":0},"latestRun":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"runDate":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"totalChecked":{"type":"integer","minimum":0},"clearCount":{"type":"integer","minimum":0},"matchCount":{"type":"integer","minimum":0},"errorCount":{"type":"integer","minimum":0},"nextRunDate":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","runDate","completedAt","totalChecked","clearCount","matchCount","errorCount","nextRunDate"]}},"required":["status","scope","dryRun","employeeCount","providerCount","estimatedScreenableCount","latestRun"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"status":"SIMULATED_ONLY","scope":"EMPLOYEES","dryRun":true,"employeeCount":1,"providerCount":1,"estimatedScreenableCount":1,"latestRun":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","runDate":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","totalChecked":1,"clearCount":1,"matchCount":1,"errorCount":1,"nextRunDate":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/oig-exclusion/checks/{checkId}/resolution":{"put":{"operationId":"resolveOigExclusionMatch","summary":"Resolve OIG exclusion match","description":"Records a human false-positive or confirmed-excluded decision for an organization-owned OIG exclusion check in a resolvable status.\n\n### When to use\nUse this endpoint after an authorized human reviewer has compared the local match summary against approved compliance evidence and decided whether the match is false positive or confirmed excluded.\n\n### Before calling\nAuthenticate with `oig-exclusion:write` scope. Retrieve the check first, confirm it belongs to the authenticated organization, and confirm its status is `EXC_MATCH_FOUND` or `EXC_REVIEW_NEEDED`. Keep review notes concise and free of raw source payloads, credentials, DOB, SSN, or unnecessary sensitive identifiers.\n\n### Request guidance\n`checkId` is a required path parameter. `resolution` is required and must be `FALSE_POSITIVE` or `CONFIRMED_EXCLUDED`. `notes` is optional, must be non-empty when supplied, and is capped at 4000 characters.\n\n### Request notes\n- `resolution` must be `FALSE_POSITIVE` or `CONFIRMED_EXCLUDED`.\n- Only checks currently in `EXC_MATCH_FOUND` or `EXC_REVIEW_NEEDED` status are resolvable.\n- `notes` should summarize the decision rationale without raw LEIE/SAM.gov rows, secrets, DOB, SSN, or unrelated PHI.\n- Use this endpoint only after human review; it is not a source-list search endpoint.\n\n### Response semantics\nA 200 response returns the resolved sanitized check in `data.check` plus `meta.organizationId`. False-positive resolution changes the local status to `EXC_FALSE_POSITIVE`; confirmed-excluded resolution changes it to `EXC_CONFIRMED_EXCLUDED` and can attempt internal organization-scoped follow-up such as audit logging, admin notification, credentialing flags, or claim-hold attempts where those models support it. The public response itself is not proof that external EHR write-back, payer notification, or claim holds completed.\n\n### Response notes\n- The response returns the local check record after resolution.\n- `reviewedBy` and `reviewedAt` may be populated by the server when the resolution is recorded.\n- `status` changes to `EXC_FALSE_POSITIVE` for false-positive resolution or `EXC_CONFIRMED_EXCLUDED` for confirmed-excluded resolution.\n- `matchSummary`, `leie`, and `sam` remain structured summaries on the returned check; the public response does not expose raw source-list evidence or reviewer notes.\n- Confirmed-excluded resolution can trigger internal follow-up attempts, but the response should not be documented as proof of completed claims, credentialing, payer, or external EHR side effects.\n- The public check serializer returns `reviewedBy` and `reviewedAt`, but not raw reviewer notes.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization `checkId`. Treat 400 as invalid request body or a non-resolvable current status; only `EXC_MATCH_FOUND` and `EXC_REVIEW_NEEDED` checks can be resolved. After a timeout, fetch the check before submitting another resolution to avoid duplicate or conflicting review notes.\n\n### Error notes\n- 400 can indicate an unsupported resolution value, invalid notes length, or a check status other than `EXC_MATCH_FOUND` or `EXC_REVIEW_NEEDED`.\n- 404 means the check is not available in the authenticated organization.\n- 403 means the caller lacks authorization for the organization context or write scope.\n","tags":["OIG Exclusion"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"checkId","in":"path","description":"Identifier of the local OIG exclusion check to resolve."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string","enum":["FALSE_POSITIVE","CONFIRMED_EXCLUDED"],"description":"Human review outcome: `FALSE_POSITIVE` or `CONFIRMED_EXCLUDED`."},"notes":{"type":"string","minLength":1,"maxLength":4000,"description":"Optional reviewer notes, capped at 4000 characters. Keep notes sanitized and avoid raw source data, DOB, SSN, secrets, and unrelated PHI."}},"required":["resolution"]},"example":{"resolution":"FALSE_POSITIVE","notes":"Example oig_exclusion_match note"}}},"description":"`checkId` is a required path parameter. `resolution` is required and must be `FALSE_POSITIVE` or `CONFIRMED_EXCLUDED`. `notes` is optional, must be non-empty when supplied, and is capped at 4000 characters."},"responses":{"200":{"description":"Resolved OIG exclusion check for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"check":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"checkType":{"type":"string","enum":["PROVIDER","EMPLOYEE","CONTRACTOR","VENDOR"]},"entityName":{"type":"string"},"npi":{"type":["string","null"]},"userId":{"type":["string","null"]},"providerId":{"type":["string","null"]},"status":{"type":"string","enum":["EXC_CLEAR","EXC_MATCH_FOUND","EXC_REVIEW_NEEDED","EXC_FALSE_POSITIVE","EXC_CONFIRMED_EXCLUDED","EXC_ERROR"]},"matchSummary":{"type":["object","null"],"properties":{"leieMatch":{"type":"boolean"},"samMatch":{"type":"boolean"},"matchScore":{"type":["number","null"]}},"required":["leieMatch","samMatch","matchScore"]},"leie":{"type":["object","null"],"properties":{"exclusionType":{"type":["string","null"]},"exclusionDate":{"type":["string","null"],"format":"date-time"},"reinstatementDate":{"type":["string","null"],"format":"date-time"},"state":{"type":["string","null"]},"specialty":{"type":["string","null"]}},"required":["exclusionType","exclusionDate","reinstatementDate","state","specialty"]},"sam":{"type":["object","null"],"properties":{"exclusionType":{"type":["string","null"]},"exclusionDate":{"type":["string","null"],"format":"date-time"}},"required":["exclusionType","exclusionDate"]},"reviewedBy":{"type":["string","null"]},"reviewedAt":{"type":["string","null"],"format":"date-time"},"checkedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","checkType","entityName","npi","userId","providerId","status","matchSummary","leie","sam","reviewedBy","reviewedAt","checkedAt"]}},"required":["check"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"check":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","checkType":"PROVIDER","entityName":"Example oig_exclusion_match","npi":"1234567893","userId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","status":"EXC_CLEAR","matchSummary":{"leieMatch":true,"samMatch":true,"matchScore":1.25},"leie":{"exclusionType":"example-exclusiontype","exclusionDate":"2026-06-08T10:15:30Z","reinstatementDate":"2026-06-08T10:15:30Z","state":"example-state","specialty":"example-specialty"},"sam":{"exclusionType":"example-exclusiontype","exclusionDate":"2026-06-08T10:15:30Z"},"reviewedBy":"example-reviewedby","reviewedAt":"2026-06-08T10:15:30Z","checkedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"OIG exclusion check not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/accounts":{"get":{"operationId":"listPatientArAccounts","summary":"List patient AR accounts","description":"Lists patient accounts receivable accounts owned by the organization selected by the bearer API key.\n\n### When to use\nUse this to build patient-balance worklists, find an account before posting a charge or payment, monitor collection status, or reconcile local Patient AR account counts.\n\n### Before calling\nAuthenticate with `patient-ar:read` or `patient-ar:write`. Choose bounded pagination and the narrowest available filters for status, collection status, patient, facility, balance range, or search text.\n\n### Request guidance\n`page` is one-based and defaults to 1. `pageSize` defaults to 25 and is capped at 100. The `search` filter is capped at 120 characters and searches account number, patient MRN, and patient name, so clients should avoid logging raw search terms.\n\n### Request notes\n- Do not send `organizationId`; tenant context comes from the API key.\n- `status` accepts ACTIVE, ON_HOLD, IN_COLLECTIONS, CLOSED, or WRITTEN_OFF.\n- `collectionStatus` accepts CURRENT, PAST_DUE, PRE_COLLECT, IN_COLLECT, AGENCY, LEGAL, PAYMENT_PLAN, or HARDSHIP.\n- `minBalance` and `maxBalance` are numeric lower and upper bounds for current balance.\n\n### Response semantics\nHTTP 200 returns local account summaries in `data.accounts`, total counts, page metadata, and `meta.organizationId`. Account rows include patient and guarantor references, facility reference, balance strings, collection/status fields, timestamps, and counts of related charges, payments, statements, payment plans, and collection tasks.\n\n### Response notes\n- `currentBalance`, `charityAmount`, and `lastPaymentAmount` are decimal monetary values serialized as strings.\n- `patient` and `guarantor` include identifiers, MRN, first name, and last name; examples must be synthetic.\n- `counts` are local relationship counts, not external collection or payment processing evidence.\n- `status` is the local account lifecycle status, not an HTTP or operation-result status.\n\n### Errors and retries\nTreat 400 as invalid filters or pagination, 401 as authentication failure, 403 as scope or RBAC failure, and 429 as a backoff signal. Retrying the same read with the same filters is safe after transient failures.\n\n### Error notes\n- 403 can mean the API key is valid but lacks Patient AR access.\n- 429 means the public API rate limit was exceeded.\n- Avoid broad polling loops over account lists that can contain PHI-adjacent context.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query","description":"One-based result page. Defaults to 1."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"Number of accounts per page. Defaults to 25 and is capped at 100."},{"schema":{"type":"string","enum":["ACTIVE","ON_HOLD","IN_COLLECTIONS","CLOSED","WRITTEN_OFF"],"description":"Patient AR account lifecycle status."},"required":false,"description":"Optional Patient AR account lifecycle status filter.","name":"status","in":"query"},{"schema":{"type":"string","enum":["CURRENT","PAST_DUE","PRE_COLLECT","IN_COLLECT","AGENCY","LEGAL","PAYMENT_PLAN","HARDSHIP"],"description":"Patient AR collection workflow status."},"required":false,"description":"Optional collection workflow status filter.","name":"collectionStatus","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"patientId","in":"query","description":"Optional QuickRCM patient identifier scoped to the authenticated organization."},{"schema":{"type":"string","minLength":1},"required":false,"name":"facilityId","in":"query","description":"Optional QuickRCM facility identifier scoped to the authenticated organization."},{"schema":{"type":["number","null"],"minimum":0},"required":false,"name":"minBalance","in":"query","description":"Optional minimum current balance filter."},{"schema":{"type":["number","null"],"minimum":0},"required":false,"name":"maxBalance","in":"query","description":"Optional maximum current balance filter."},{"schema":{"type":"string","minLength":1,"maxLength":120,"description":"Searches account number, patient MRN, and patient name."},"required":false,"description":"Optional text filter over account number, patient MRN, and patient name. Treat raw search terms as sensitive.","name":"search","in":"query"}],"responses":{"200":{"description":"Patient AR accounts for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"guarantorId":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"accountNumber":{"type":"string"},"currentBalance":{"type":"string","description":"Decimal monetary amount serialized as a string."},"collectionStatus":{"type":"string","enum":["CURRENT","PAST_DUE","PRE_COLLECT","IN_COLLECT","AGENCY","LEGAL","PAYMENT_PLAN","HARDSHIP"],"description":"Patient AR collection workflow status."},"collectionScore":{"type":["number","null"]},"status":{"type":"string","enum":["ACTIVE","ON_HOLD","IN_COLLECTIONS","CLOSED","WRITTEN_OFF"],"description":"Patient AR account lifecycle status."},"financialClass":{"type":["string","null"]},"badDebtDate":{"type":["string","null"],"format":"date-time"},"charityAmount":{"type":"string","description":"Decimal monetary amount serialized as a string."},"hardshipApproved":{"type":"boolean"},"hardshipDate":{"type":["string","null"],"format":"date-time"},"lastActivityDate":{"type":["string","null"],"format":"date-time"},"lastPaymentDate":{"type":["string","null"],"format":"date-time"},"lastPaymentAmount":{"type":["string","null"],"description":"Decimal monetary amount serialized as a string."},"lastStatementDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"patient":{"type":"object","properties":{"id":{"type":"string"},"mrn":{"type":["string","null"]},"firstName":{"type":"string"},"lastName":{"type":"string"}},"required":["id","mrn","firstName","lastName"]},"guarantor":{"type":["object","null"],"properties":{"id":{"type":"string"},"mrn":{"type":["string","null"]},"firstName":{"type":"string"},"lastName":{"type":"string"}},"required":["id","mrn","firstName","lastName"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"counts":{"type":"object","properties":{"charges":{"type":"integer"},"payments":{"type":"integer"},"statements":{"type":"integer"},"paymentPlans":{"type":"integer"},"collectionTasks":{"type":"integer"}},"required":["charges","payments","statements","paymentPlans","collectionTasks"]}},"required":["id","organizationId","patientId","guarantorId","facilityId","accountNumber","currentBalance","collectionStatus","collectionScore","status","financialClass","badDebtDate","charityAmount","hardshipApproved","hardshipDate","lastActivityDate","lastPaymentDate","lastPaymentAmount","lastStatementDate","createdAt","updatedAt","patient","guarantor","facility","counts"]}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["accounts","total","page","pageSize","totalPages"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"accounts":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","guarantorId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","accountNumber":"example-accountnumber","currentBalance":"example-currentbalance","collectionStatus":"CURRENT","collectionScore":1.25,"status":"ACTIVE","financialClass":"example-financialclass","badDebtDate":"2026-06-08T10:15:30Z","charityAmount":"example-charityamount","hardshipApproved":true,"hardshipDate":"2026-06-08T10:15:30Z","lastActivityDate":"2026-06-08T10:15:30Z","lastPaymentDate":"2026-06-08T10:15:30Z","lastPaymentAmount":"example-lastpaymentamount","lastStatementDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","patient":{"id":"00000000-0000-4000-8000-000000000001","mrn":"example-mrn","firstName":"John","lastName":"Smith"},"guarantor":{"id":"00000000-0000-4000-8000-000000000001","mrn":"example-mrn","firstName":"John","lastName":"Smith"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example patient_ar_account"},"counts":{"charges":125.5,"payments":1,"statements":1,"paymentPlans":1,"collectionTasks":1}}],"total":1,"page":1,"pageSize":1,"totalPages":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createPatientArAccount","summary":"Create patient AR account","description":"Creates a local Patient AR account after verifying the patient, optional guarantor, and optional facility belong to the authenticated organization.\n\n### When to use\nUse this when a patient balance workflow needs a local AR account before charges, statements, payment plans, deposits, or collection tasks can be recorded.\n\n### Before calling\nResolve the same-tenant `patientId`; optionally resolve a guarantor patient and facility. Check whether the patient already has a Patient AR account to avoid duplicate-account conflicts.\n\n### Request guidance\n`patientId` is required. `currentBalance` defaults to 0, `collectionStatus` defaults to CURRENT, and `status` defaults to ACTIVE. If `accountNumber` is omitted, the handler generates one from an AR prefix and the idempotency marker or timestamp. Keep `notes` PHI-minimal.\n\n### Request notes\n- `patientId` must resolve to a patient in the API key organization.\n- `guarantorId` is another patient identifier and must also resolve in the same organization when supplied.\n- `idempotencyKey` is stored in local metadata; current evidence does not show idempotent replay or duplicate suppression.\n\n### Response semantics\nHTTP 201 returns a local write acknowledgement with `resourceType: PatientAccount`, operation-result `status: CREATED`, `externalRisk: LOCAL_ONLY`, and a nested `account` detail. It does not create charges, statements, collection placements, or payment plans.\n\n### Response notes\n- `externalRisk: LOCAL_ONLY` means the endpoint only created QuickRCM local state.\n- The returned nested account uses decimal strings for monetary balances.\n- The operation-result `data.status` differs from nested `account.status`, which is the account lifecycle status.\n\n### Errors and retries\nFix 400 validation errors and 404 referenced-resource failures before retrying. The handler can return a duplicate-account conflict when an account already exists for the patient, although the current generated OpenAPI common error set does not list 409. After a timeout, list by patient context before creating another account.\n\n### Error notes\n- 404 can mean the patient, guarantor, or facility was not found in the authenticated organization.\n- 409 duplicate-account behavior is evidenced in the handler but is not currently represented in the common OpenAPI error responses.\n- Do not blind-retry creates after connection timeouts.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"Required QuickRCM patient identifier for the account."},"guarantorId":{"type":"string","minLength":1,"description":"Optional QuickRCM patient identifier used as account guarantor."},"facilityId":{"type":"string","minLength":1,"description":"Optional facility identifier scoped to the authenticated organization."},"accountNumber":{"type":"string","minLength":1,"maxLength":120,"description":"Optional caller-provided account number. Treat as sensitive financial context."},"currentBalance":{"type":["number","null"],"minimum":0,"default":0,"description":"Initial local account balance. Defaults to 0."},"collectionStatus":{"type":"string","enum":["CURRENT","PAST_DUE","PRE_COLLECT","IN_COLLECT","AGENCY","LEGAL","PAYMENT_PLAN","HARDSHIP"],"default":"CURRENT","description":"Initial collection workflow status. Defaults to CURRENT."},"status":{"type":"string","enum":["ACTIVE","ON_HOLD","IN_COLLECTIONS","CLOSED","WRITTEN_OFF"],"default":"ACTIVE","description":"Initial account lifecycle status. Defaults to ACTIVE."},"financialClass":{"type":"string","minLength":1,"maxLength":80,"description":"Optional local financial class label capped at 80 characters."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional staff note capped at 2000 characters. Avoid secrets and unnecessary PHI."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker stored in local metadata and used when generating a public account number."}},"required":["patientId"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","guarantorId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","accountNumber":"example-accountnumber","currentBalance":0,"collectionStatus":"CURRENT","status":"ACTIVE","financialClass":"example-financialclass","notes":"Example patient_ar_account note"}}},"description":"`patientId` is required. `currentBalance` defaults to 0, `collectionStatus` defaults to CURRENT, and `status` defaults to ACTIVE. If `accountNumber` is omitted, the handler generates one from an AR prefix and the idempotency marker or timestamp. Keep `notes` PHI-minimal."},"responses":{"201":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/accounts/{accountId}":{"get":{"operationId":"getPatientArAccount","summary":"Get patient AR account","description":"Returns one organization-scoped Patient AR account with the same account detail shape used by list responses.\n\n### When to use\nUse this after listPatientArAccounts or another trusted QuickRCM response gives you an `accountId` for the same tenant.\n\n### Before calling\nAuthenticate with `patient-ar:read` or `patient-ar:write`. Use an account identifier obtained under the same API-key organization context.\n\n### Request guidance\nPass `accountId` in the path. No request body is accepted and the query schema is empty.\n\n### Request notes\n- `accountId` is path-only.\n- Do not guess account IDs across organizations.\n- Do not include PHI or account notes in the request.\n\n### Response semantics\nHTTP 200 returns local account detail, including patient, guarantor, facility, balances, status, collection fields, timestamps, and related-record counts. It is not a statement, payment receipt, or collection agency status.\n\n### Response notes\n- The response includes local account state and related-count rollups.\n- Use payment, charge, statement, or collection endpoints for workflow mutations.\n- `meta.organizationId` echoes the authenticated tenant context.\n- `createdAt` and `updatedAt` are account row timestamps, not statement or payment dates.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization account context unless a prior trusted response proves the account should exist. Retry only transient 5xx or 429 responses.\n\n### Error notes\n- 404 intentionally covers missing and inaccessible account IDs.\n- 401 and 403 require credential, scope, or RBAC correction.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"accountId","in":"path","description":"QuickRCM Patient AR account identifier in the path. It must belong to the API key organization."}],"responses":{"200":{"description":"Patient AR account detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"guarantorId":{"type":["string","null"]},"facilityId":{"type":["string","null"]},"accountNumber":{"type":"string"},"currentBalance":{"type":"string","description":"Decimal monetary amount serialized as a string."},"collectionStatus":{"type":"string","enum":["CURRENT","PAST_DUE","PRE_COLLECT","IN_COLLECT","AGENCY","LEGAL","PAYMENT_PLAN","HARDSHIP"],"description":"Patient AR collection workflow status."},"collectionScore":{"type":["number","null"]},"status":{"type":"string","enum":["ACTIVE","ON_HOLD","IN_COLLECTIONS","CLOSED","WRITTEN_OFF"],"description":"Patient AR account lifecycle status."},"financialClass":{"type":["string","null"]},"badDebtDate":{"type":["string","null"],"format":"date-time"},"charityAmount":{"type":"string","description":"Decimal monetary amount serialized as a string."},"hardshipApproved":{"type":"boolean"},"hardshipDate":{"type":["string","null"],"format":"date-time"},"lastActivityDate":{"type":["string","null"],"format":"date-time"},"lastPaymentDate":{"type":["string","null"],"format":"date-time"},"lastPaymentAmount":{"type":["string","null"],"description":"Decimal monetary amount serialized as a string."},"lastStatementDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"patient":{"type":"object","properties":{"id":{"type":"string"},"mrn":{"type":["string","null"]},"firstName":{"type":"string"},"lastName":{"type":"string"}},"required":["id","mrn","firstName","lastName"]},"guarantor":{"type":["object","null"],"properties":{"id":{"type":"string"},"mrn":{"type":["string","null"]},"firstName":{"type":"string"},"lastName":{"type":"string"}},"required":["id","mrn","firstName","lastName"]},"facility":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"counts":{"type":"object","properties":{"charges":{"type":"integer"},"payments":{"type":"integer"},"statements":{"type":"integer"},"paymentPlans":{"type":"integer"},"collectionTasks":{"type":"integer"}},"required":["charges","payments","statements","paymentPlans","collectionTasks"]}},"required":["id","organizationId","patientId","guarantorId","facilityId","accountNumber","currentBalance","collectionStatus","collectionScore","status","financialClass","badDebtDate","charityAmount","hardshipApproved","hardshipDate","lastActivityDate","lastPaymentDate","lastPaymentAmount","lastStatementDate","createdAt","updatedAt","patient","guarantor","facility","counts"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","guarantorId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","accountNumber":"example-accountnumber","currentBalance":"example-currentbalance","collectionStatus":"CURRENT","collectionScore":1.25,"status":"ACTIVE","financialClass":"example-financialclass","badDebtDate":"2026-06-08T10:15:30Z","charityAmount":"example-charityamount","hardshipApproved":true,"hardshipDate":"2026-06-08T10:15:30Z","lastActivityDate":"2026-06-08T10:15:30Z","lastPaymentDate":"2026-06-08T10:15:30Z","lastPaymentAmount":"example-lastpaymentamount","lastStatementDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","patient":{"id":"00000000-0000-4000-8000-000000000001","mrn":"example-mrn","firstName":"John","lastName":"Smith"},"guarantor":{"id":"00000000-0000-4000-8000-000000000001","mrn":"example-mrn","firstName":"John","lastName":"Smith"},"facility":{"id":"00000000-0000-4000-8000-000000000001","name":"Example patient_ar_account"},"counts":{"charges":125.5,"payments":1,"statements":1,"paymentPlans":1,"collectionTasks":1}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"updatePatientArAccount","summary":"Update patient AR account","description":"Updates safe local account status, collection status, collection score, hardship, charity amount, financial class, and note fields on an organization-scoped Patient AR account.\n\n### When to use\nUse this for local account lifecycle or collection workflow maintenance after the account already exists.\n\n### Before calling\nResolve the account under the same API-key organization and decide whether the change is account lifecycle status, collection workflow status, hardship state, or charity metadata.\n\n### Request guidance\nSend `accountId` in the path and only the fields to update. `collectionScore` must be 0 through 100. `hardshipDate` must be an ISO date-time when supplied. Notes should be operational and PHI-minimal.\n\n### Request notes\n- `status` changes the account lifecycle status.\n- `collectionStatus` changes the collection workflow status.\n- `charityAmount` is local account metadata and not a payment.\n\n### Response semantics\nHTTP 200 returns `resourceType: PatientAccount`, operation-result `status: UPDATED`, `externalRisk: LOCAL_ONLY`, and a nested updated account. The handler also updates `lastActivityDate`.\n\n### Response notes\n- The operation-result status is `UPDATED`; nested `account.status` is the account lifecycle status.\n- `lastActivityDate` is refreshed by the handler.\n- No external contact, payment, statement delivery, or collection placement is triggered.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization account. Re-read the account after a timeout before sending another status or balance-affecting update.\n\n### Error notes\n- 400 can indicate invalid enum, amount, score, or date values.\n- 404 hides both missing and wrong-tenant account IDs.\n- Do not retry blindly after ambiguous write timeouts.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"accountId","in":"path","description":"Patient AR account identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ACTIVE","ON_HOLD","IN_COLLECTIONS","CLOSED","WRITTEN_OFF"],"description":"Optional local account lifecycle status."},"collectionStatus":{"type":"string","enum":["CURRENT","PAST_DUE","PRE_COLLECT","IN_COLLECT","AGENCY","LEGAL","PAYMENT_PLAN","HARDSHIP"],"description":"Optional collection workflow status."},"collectionScore":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Optional local collection score from 0 through 100."},"financialClass":{"type":"string","minLength":1,"maxLength":80,"description":"Optional local financial class label."},"hardshipApproved":{"type":"boolean","description":"Optional hardship approval flag."},"hardshipDate":{"type":"string","format":"date-time","description":"Optional ISO date-time for hardship approval or review."},"charityAmount":{"type":["number","null"],"minimum":0,"description":"Optional local charity amount."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional staff note capped at 2000 characters."}}},"example":{"status":"ACTIVE","collectionStatus":"CURRENT","collectionScore":1.25,"financialClass":"example-financialclass","hardshipApproved":true,"hardshipDate":"2026-06-08T10:15:30Z","charityAmount":125.5,"notes":"Example patient_ar_account note"}}},"description":"Send `accountId` in the path and only the fields to update. `collectionScore` must be 0 through 100. `hardshipDate` must be an ISO date-time when supplied. Notes should be operational and PHI-minimal."},"responses":{"200":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/accounts/{accountId}/charges":{"post":{"operationId":"postPatientArCharge","summary":"Post patient AR charge","description":"Posts a local patient-responsibility charge to an organization-scoped Patient AR account and increments the account current balance.\n\n### When to use\nUse this when a patient-responsibility amount needs to be represented as a local AR charge after upstream billing, claim, or responsibility workflows determine the amount.\n\n### Before calling\nResolve the account. Optionally resolve same-tenant facility, claim, and claim-line identifiers when the charge should be linked to those records.\n\n### Request guidance\n`serviceDate`, `description`, and positive `amount` are required. `icdCodes` defaults to an empty array. Optional `claimLineId` is verified through the authenticated organization and optional `claimId` when provided.\n\n### Request notes\n- `amount` must be positive.\n- `serviceDate` must be an ISO date-time.\n- `claimId` and `claimLineId` are optional links to local claim context, not external claim submission.\n\n### Response semantics\nHTTP 201 returns `resourceType: PatientCharge`, `status: CREATED`, and `externalRisk: LOCAL_ONLY`. The handler creates a local charge with status OPEN and updates account balance; it does not submit or modify a claim externally.\n\n### Response notes\n- The response is a local write acknowledgement.\n- The account balance is incremented by the charge amount.\n- Use getPatientArAccount or listPatientArAccounts to observe the account-level balance after posting.\n\n### Errors and retries\nFix invalid dates, missing fields, and nonpositive amounts after 400. Treat 404 as account, facility, claim, or claim-line lookup failure in the authenticated organization.\n\n### Error notes\n- 404 can mean a supplied claim or claim line is unavailable to this tenant.\n- Do not retry a successful charge create with a new idempotency key after timeout without checking account state.\n- The public response does not include the full created charge body.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"accountId","in":"path","description":"Patient AR account receiving the charge."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serviceDate":{"type":"string","format":"date-time","description":"ISO date-time for the underlying service date."},"description":{"type":"string","minLength":1,"maxLength":500,"description":"Charge description capped at 500 characters. Avoid unnecessary PHI."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Positive local charge amount."},"claimId":{"type":"string","minLength":1,"description":"Optional same-tenant QuickRCM claim identifier to link the charge."},"claimLineId":{"type":"string","minLength":1,"description":"Optional claim-line identifier verified within the same organization and optional claim."},"facilityId":{"type":"string","minLength":1,"description":"Optional same-tenant facility identifier."},"cptCode":{"type":"string","minLength":1,"maxLength":32,"description":"Optional procedure code capped at 32 characters."},"icdCodes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":32},"default":[],"description":"Optional array of diagnosis codes, each capped at 32 characters."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional staff note capped at 2000 characters."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional marker stored in local metadata."}},"required":["serviceDate","description","amount"]},"example":{"serviceDate":"2026-06-08T10:15:30Z","description":"Example post_patient_ar_charge note","amount":125.5,"claimId":"00000000-0000-4000-8000-000000000001","claimLineId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","cptCode":"example-cptcode","icdCodes":[],"notes":"Example post_patient_ar_charge note","idempotencyKey":"example-idempotencykey"}}},"description":"`serviceDate`, `description`, and positive `amount` are required. `icdCodes` defaults to an empty array. Optional `claimLineId` is verified through the authenticated organization and optional `claimId` when provided."},"responses":{"201":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/accounts/{accountId}/adjustments":{"post":{"operationId":"adjustPatientArCharge","summary":"Adjust patient AR charge","description":"Applies a local positive adjustment amount to a charge on the selected Patient AR account and decrements the account current balance.\n\n### When to use\nUse this to record a local balance-reducing charge adjustment such as an approved write-down, correction, or administrative adjustment.\n\n### Before calling\nResolve the account and charge from the same tenant. Confirm the adjustment amount and reason against local financial policy before calling.\n\n### Request guidance\n`chargeId`, positive `adjustmentAmount`, and `reason` are required. The charge must belong to the account in the path. `notes` overrides `reason` as the persisted note when supplied by the current handler.\n\n### Request notes\n- `adjustmentAmount` must be positive.\n- `reason` is required even though the current handler persists `notes` when notes are supplied.\n- This endpoint is not a payment refund, payer adjustment import, or external write-off submission.\n\n### Response semantics\nHTTP 200 returns `resourceType: PatientCharge`, `status: ADJUSTED`, and `externalRisk: LOCAL_ONLY`. The handler increments charge adjustments, decrements charge balance and account balance, and marks the charge adjusted when the adjustment is at least the prior charge balance.\n\n### Response notes\n- The response is local acknowledgement only.\n- The public response does not return the full updated charge row.\n- Use account reads for account balance verification.\n\n### Errors and retries\nTreat 404 as account or charge lookup failure. Re-read the account and charge after timeouts before retrying because this endpoint changes balances.\n\n### Error notes\n- 400 can indicate invalid body shape or amount.\n- 404 can mean the charge does not belong to the account or organization.\n- Current handler evidence does not show a cap preventing an adjustment greater than the charge balance.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"accountId","in":"path","description":"Patient AR account identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chargeId":{"type":"string","minLength":1,"description":"Local Patient AR charge identifier to adjust."},"adjustmentAmount":{"type":"number","exclusiveMinimum":0,"description":"Positive amount to subtract from the local charge and account balance."},"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Required short adjustment reason capped at 500 characters."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional adjustment note. If supplied, current handler uses it instead of `reason` for the charge notes field."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker stored in local metadata."}},"required":["chargeId","adjustmentAmount","reason"]},"example":{"chargeId":"00000000-0000-4000-8000-000000000001","adjustmentAmount":125.5,"reason":"example-reason","notes":"Example adjust_patient_ar_charge note","idempotencyKey":"example-idempotencykey"}}},"description":"`chargeId`, positive `adjustmentAmount`, and `reason` are required. The charge must belong to the account in the path. `notes` overrides `reason` as the persisted note when supplied by the current handler."},"responses":{"200":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/payments":{"post":{"operationId":"createPatientArPayment","summary":"Create patient AR payment","description":"Creates a local non-card Patient AR payment record or validates/dry-runs/returns a queue-only acknowledgement for card, debit, and ACH payment requests without calling Stripe directly.\n\n### When to use\nUse this for local cash, check, wire, or other payment posting, or for safe public validation and queue-only acknowledgement paths for card/debit/ACH requests.\n\n### Before calling\nResolve the account. Optionally resolve a payment plan on that account and a deposit batch in the organization. Choose a payment method and a stable idempotency key for the same request.\n\n### Request guidance\n`accountId`, positive `amount`, `method`, and `idempotencyKey` are required. For CREDIT_CARD, DEBIT_CARD, or ACH, set `validateOnly` or `dryRun` for simulation, or set `queueOnly: true` to receive a queued-only acknowledgement; otherwise the handler returns 400. For CHECK, CASH, WIRE_TRANSFER, or OTHER, the handler creates a local COMPLETED payment record.\n\n### Request notes\n- `idempotencyKey` is required and capped at 128 characters.\n- `queueOnly` is required for public card, debit, and ACH requests unless `validateOnly` or `dryRun` is true.\n- `autoApply` is present in the schema but current handler evidence does not show automatic application behavior.\n\n### Response semantics\nLocal payment methods return HTTP 201 with `status: COMPLETED` and `externalRisk: LOCAL_ONLY`. External payment methods return HTTP 200 VALIDATED with `SIMULATED_ONLY` for validation/dry run, or HTTP 202 QUEUED with `QUEUED_ONLY` for queue-only requests. The current generated OpenAPI response list shows 201 only, so final docs should explicitly reconcile the handler-level 200 and 202 branches before publication. Creating a local payment does not itself apply the payment to charges; use applyPatientArPayment for applications.\n\n### Response notes\n- `externalRisk` communicates LOCAL_ONLY, QUEUED_ONLY, or SIMULATED_ONLY behavior.\n- HTTP 202 means queued-only acknowledgement, not completed card or ACH processing.\n- A COMPLETED local payment still needs explicit applications to decrement account balance.\n\n### Errors and retries\nFix 400 mode, method, or body errors before retrying. Treat 404 as missing account, payment plan, or deposit batch. After timeouts, inspect local payment state available to the integration before repeating a money-related create; current evidence does not show a public queued-workflow lookup path.\n\n### Error notes\n- 400 is expected if a card, debit, or ACH request omits safe mode controls.\n- 404 can mean `paymentPlanId` does not belong to the account.\n- Do not describe a queued external payment as captured, settled, or posted to Stripe.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","minLength":1,"description":"Patient AR account receiving the payment record."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Positive payment amount."},"method":{"type":"string","enum":["CREDIT_CARD","DEBIT_CARD","ACH","CHECK","CASH","WIRE_TRANSFER","OTHER"],"description":"Payment method enum: CREDIT_CARD, DEBIT_CARD, ACH, CHECK, CASH, WIRE_TRANSFER, or OTHER."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Required caller marker for this payment request. Current evidence shows metadata storage, not guaranteed replay suppression."},"queueOnly":{"type":"boolean","default":false,"description":"For card, debit, and ACH, returns a queued-only acknowledgement instead of direct Stripe execution."},"validateOnly":{"type":"boolean","default":false,"description":"Validates an external payment request without creating a local payment or queue mutation."},"dryRun":{"type":"boolean","default":false,"description":"Simulates an external payment request without creating a local payment or queue mutation."},"autoApply":{"type":"boolean","default":false,"description":"Schema flag defaulting to false; current handler evidence does not show application behavior."},"paymentPlanId":{"type":"string","minLength":1,"description":"Optional payment plan identifier that must belong to the same account."},"depositBatchId":{"type":"string","minLength":1,"description":"Optional deposit batch identifier scoped to the same organization."},"checkNumber":{"type":"string","minLength":1,"maxLength":80,"description":"Optional check number for check-style local payments."},"checkDate":{"type":"string","format":"date-time","description":"Optional check date-time for check-style local payments."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional staff note. Do not include card data or credentials."}},"required":["accountId","amount","method","idempotencyKey"]},"example":{"accountId":"00000000-0000-4000-8000-000000000001","amount":125.5,"method":"CREDIT_CARD","idempotencyKey":"example-idempotencykey","queueOnly":false,"validateOnly":false,"dryRun":false,"autoApply":false,"paymentPlanId":"00000000-0000-4000-8000-000000000001","depositBatchId":"00000000-0000-4000-8000-000000000001","checkNumber":"example-checknumber","checkDate":"2026-06-08T10:15:30Z"}}},"description":"`accountId`, positive `amount`, `method`, and `idempotencyKey` are required. For CREDIT_CARD, DEBIT_CARD, or ACH, set `validateOnly` or `dryRun` for simulation, or set `queueOnly: true` to receive a queued-only acknowledgement; otherwise the handler returns 400. For CHECK, CASH, WIRE_TRANSFER, or OTHER, the handler creates a local COMPLETED payment record."},"responses":{"201":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/payments/{paymentId}/applications":{"post":{"operationId":"applyPatientArPayment","summary":"Apply patient AR payment","description":"Applies an existing organization-scoped patient payment to one or more local charges on the payment account and updates charge and account balances.\n\n### When to use\nUse this after a local payment record exists and the integration knows how the payment should be allocated across open patient charges.\n\n### Before calling\nResolve the payment and target charges in the same organization. Confirm the total application amount does not exceed the payment amount.\n\n### Request guidance\nSend one or more application objects with `chargeId` and positive `amount`. Every charge must belong to the same account as the payment. The handler rejects totals greater than the payment amount.\n\n### Request notes\n- `applications` must contain at least one item.\n- Each application amount must be positive.\n- The total application amount cannot exceed the payment amount.\n\n### Response semantics\nHTTP 200 returns `resourceType: PatientPayment`, `status: APPLIED`, and `externalRisk: LOCAL_ONLY`. The handler creates local application rows, decrements charge balances, sets fully covered charges to PAID, marks the payment COMPLETED, and decrements the account current balance by the total applied.\n\n### Response notes\n- This endpoint mutates local charge and account balances.\n- The public response is an acknowledgement, not a receipt document.\n- It does not initiate external funds movement.\n\n### Errors and retries\nTreat 400 as over-application or invalid body. Treat 404 as payment or charge lookup failure in the authenticated organization. Re-read payment and account state after timeouts before retrying.\n\n### Error notes\n- 404 can include an individual missing charge from the application list.\n- Retrying after timeout can duplicate application rows unless the previous result is checked.\n- The optional `idempotencyKey` is accepted but current handler evidence does not show duplicate detection.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"paymentId","in":"path","description":"Patient payment identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"applications":{"type":"array","items":{"type":"object","properties":{"chargeId":{"type":"string","minLength":1,"description":"Local charge identifier on the same account as the payment."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Positive amount to apply to the charge."}},"required":["chargeId","amount"]},"minItems":1,"description":"Array of charge application instructions. Must contain at least one item."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker accepted by the request schema."}},"required":["applications"]},"example":{"applications":[{"chargeId":"00000000-0000-4000-8000-000000000001","amount":125.5}],"idempotencyKey":"example-idempotencykey"}}},"description":"Send one or more application objects with `chargeId` and positive `amount`. Every charge must belong to the same account as the payment. The handler rejects totals greater than the payment amount."},"responses":{"200":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/payments/{paymentId}/refund":{"post":{"operationId":"refundPatientArPayment","summary":"Validate or queue patient AR refund","description":"Validates or returns a queue-only acknowledgement for a patient payment refund request for an organization-scoped payment without calling Stripe or mutating payment rows directly.\n\n### When to use\nUse this to safely check refund request shape or request queue-only handling after a payment exists.\n\n### Before calling\nResolve the payment in the same tenant. Decide whether the call is a dry run or queue-only request; default `dryRun` is true.\n\n### Request guidance\n`amount` is required and positive. With `dryRun: true`, the handler returns a validation response. With `dryRun: false`, callers must set `queueOnly: true`; otherwise the handler returns 400.\n\n### Request notes\n- `dryRun` defaults to true.\n- `queueOnly` defaults to false and is required when `dryRun` is false.\n- `reason` is optional and should be concise and PHI-minimal.\n\n### Response semantics\nHTTP 200 means VALIDATED and `externalRisk: SIMULATED_ONLY`; HTTP 202 means QUEUED and `externalRisk: QUEUED_ONLY`. The current generated OpenAPI response list shows 202 only, so final docs should reconcile the handler-level 200 dry-run branch. Neither path processes a refund, calls Stripe, or changes payment rows inline.\n\n### Response notes\n- The response echoes the requested refund amount.\n- QUEUED is queue-only acknowledgement, not external refund completion.\n- VALIDATED is simulation only.\n\n### Errors and retries\nFix missing safe-mode controls after 400. Treat 404 as missing or wrong-organization payment. Retry 429 with backoff; after timeouts, do not assume refund completion and do not rely on a public queued-workflow lookup unless one is added.\n\n### Error notes\n- 400 occurs when neither dry run nor queue-only mode protects the refund request.\n- 404 hides missing and inaccessible payments.\n- Do not document this endpoint as refund settlement.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"paymentId","in":"path","description":"Patient payment identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"Positive refund amount requested."},"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Optional refund reason capped at 500 characters."},"dryRun":{"type":"boolean","default":true,"description":"When true, simulates the refund request and avoids mutation. Defaults to true."},"queueOnly":{"type":"boolean","default":false,"description":"When true with dryRun false, returns a queued-only acknowledgement instead of direct Stripe execution."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker accepted by the request schema."}},"required":["amount"]},"example":{"amount":125.5,"reason":"example-reason","dryRun":true,"queueOnly":false,"idempotencyKey":"example-idempotencykey"}}},"description":"`amount` is required and positive. With `dryRun: true`, the handler returns a validation response. With `dryRun: false`, callers must set `queueOnly: true`; otherwise the handler returns 400."},"responses":{"202":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/payments/{paymentId}/void":{"post":{"operationId":"voidPatientArPayment","summary":"Validate or queue patient AR void","description":"Validates or returns a queue-only acknowledgement for a patient payment void request for an organization-scoped payment without calling Stripe or mutating payment rows directly.\n\n### When to use\nUse this when an integration needs a safe void workflow acknowledgement for a payment record and should avoid direct external payment actions from the public API.\n\n### Before calling\nResolve the payment in the same tenant. Decide whether to simulate with `dryRun` or use queue-only behavior; `queueOnly` defaults to true.\n\n### Request guidance\nAn empty body uses the schema defaults and returns a queued-only void acknowledgement. Set `dryRun: true` to validate without queueing. If both `dryRun` and `queueOnly` are false, the handler returns 400.\n\n### Request notes\n- `queueOnly` defaults to true.\n- `dryRun` defaults to false.\n- `reason` is optional and capped at 500 characters.\n\n### Response semantics\nHTTP 200 means VALIDATED with `externalRisk: SIMULATED_ONLY`; HTTP 202 means QUEUED with `externalRisk: QUEUED_ONLY`. The current generated OpenAPI response list shows 202 only, so final docs should reconcile the handler-level 200 dry-run branch. The response is not a completed payment void or Stripe confirmation.\n\n### Response notes\n- Default mode returns 202 QUEUED.\n- Dry-run mode returns 200 and creates no void workflow evidence in this handler.\n- No payment row mutation is performed by this public handler.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization payment. After queued-mode timeouts, do not assume external void completion; current evidence does not show a public queued-workflow lookup path.\n\n### Error notes\n- 400 occurs when dryRun is false and queueOnly is false.\n- 404 can mean the payment is outside the API key organization.\n- Do not document QUEUED as external void completion.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"paymentId","in":"path","description":"Patient payment identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Optional void reason capped at 500 characters."},"queueOnly":{"type":"boolean","default":true,"description":"Returns a queued-only void acknowledgement. Defaults to true."},"dryRun":{"type":"boolean","default":false,"description":"Validates the void request without queueing. Defaults to false."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker accepted by the request schema."}}},"example":{"reason":"example-reason","queueOnly":true,"dryRun":false,"idempotencyKey":"example-idempotencykey"}}},"description":"An empty body uses the schema defaults and returns a queued-only void acknowledgement. Set `dryRun: true` to validate without queueing. If both `dryRun` and `queueOnly` are false, the handler returns 400."},"responses":{"202":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/payment-plans":{"post":{"operationId":"createPatientArPaymentPlan","summary":"Create patient AR payment plan","description":"Creates a local DRAFT payment plan and scheduled payment rows for an organization-scoped Patient AR account.\n\n### When to use\nUse this after patient-balance review when the integration needs QuickRCM to track a payment plan schedule locally.\n\n### Before calling\nResolve the account in the same tenant. Decide cadence, installment amount, total installments, start date, and optional late-fee or missed-payment controls.\n\n### Request guidance\n`accountId`, positive `originalBalance`, positive `installmentAmount`, `frequency`, `totalInstallments`, and ISO `startDate` are required. `totalInstallments` must be 1 through 120. `stripePaymentMethodId` is a reference only; the public handler evidence does not show Stripe calls.\n\n### Request notes\n- `frequency` accepts WEEKLY, BI_WEEKLY, MONTHLY, QUARTERLY, or ONE_TIME.\n- `autoPayEnabled` does not mean the public endpoint charges a payment method.\n- Do not include real payment method IDs in examples.\n\n### Response semantics\nHTTP 201 returns `resourceType: PaymentPlan`, operation-result `status: CREATED`, and `externalRisk: LOCAL_ONLY`. The handler creates the plan with local plan status DRAFT, sets next payment date to start date, computes an end date, and creates pending scheduled-payment rows.\n\n### Response notes\n- The response is a write acknowledgement, not a full plan schedule.\n- Scheduled payments are local rows created by the handler.\n- The plan starts in DRAFT status even though the operation-result status is CREATED.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization account. After a timeout, inspect existing payment plans before retrying to avoid duplicate schedules.\n\n### Error notes\n- 400 can indicate invalid frequency, installment count, amount, or date format.\n- Current evidence does not show validation that installment math exactly matches original balance.\n- Retry creates only after checking for an existing plan.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","minLength":1,"description":"Patient AR account identifier for the plan."},"originalBalance":{"type":"number","exclusiveMinimum":0,"description":"Positive balance the plan is intended to cover."},"installmentAmount":{"type":"number","exclusiveMinimum":0,"description":"Positive recurring installment amount."},"frequency":{"type":"string","enum":["WEEKLY","BI_WEEKLY","MONTHLY","QUARTERLY","ONE_TIME"],"description":"Payment-plan cadence enum."},"totalInstallments":{"type":"integer","minimum":1,"maximum":120,"description":"Number of scheduled installments, from 1 through 120."},"startDate":{"type":"string","format":"date-time","description":"ISO date-time for the first scheduled payment."},"autoPayEnabled":{"type":"boolean","default":false,"description":"Local flag for automatic-payment expectation; it does not process a payment."},"stripePaymentMethodId":{"type":"string","minLength":1,"maxLength":255,"description":"Optional payment method reference. Treat as sensitive and synthetic in examples."},"lateFeeAmount":{"type":["number","null"],"minimum":0,"description":"Optional local late-fee amount."},"lateFeePercent":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Optional local late-fee percentage from 0 through 100."},"gracePeriodDays":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Optional grace period from 0 through 365 days."},"maxMissedPayments":{"type":["integer","null"],"minimum":0,"maximum":24,"description":"Optional maximum missed payments from 0 through 24."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker used in local metadata and generated plan number."}},"required":["accountId","originalBalance","installmentAmount","frequency","totalInstallments","startDate"]},"example":{"accountId":"00000000-0000-4000-8000-000000000001","originalBalance":125.5,"installmentAmount":125.5,"frequency":"WEEKLY","totalInstallments":1,"startDate":"2026-06-08T10:15:30Z","autoPayEnabled":false,"stripePaymentMethodId":"00000000-0000-4000-8000-000000000001","lateFeeAmount":125.5,"lateFeePercent":1.25,"gracePeriodDays":1,"maxMissedPayments":1,"idempotencyKey":"example-idempotencykey"}}},"description":"`accountId`, positive `originalBalance`, positive `installmentAmount`, `frequency`, `totalInstallments`, and ISO `startDate` are required. `totalInstallments` must be 1 through 120. `stripePaymentMethodId` is a reference only; the public handler evidence does not show Stripe calls."},"responses":{"201":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/payment-plans/{planId}":{"put":{"operationId":"updatePatientArPaymentPlan","summary":"Update patient AR payment plan","description":"Updates local payment-plan status, installment amount, next payment date, or cancellation reason for an organization-scoped payment plan.\n\n### When to use\nUse this for local payment-plan maintenance, status movement, installment changes, or cancellation after the plan already exists.\n\n### Before calling\nResolve the plan under the API key organization and decide whether the update should cancel pending scheduled payments.\n\n### Request guidance\nSend `planId` in the path and any editable fields in the body. If `status` is CANCELLED, the handler cancels pending scheduled payments for that plan in the same organization.\n\n### Request notes\n- `status` accepts DRAFT, ACTIVE, COMPLETED, CANCELLED, DEFAULTED, or ON_HOLD.\n- `nextPaymentDate` must be an ISO date-time when supplied.\n- `cancelReason` is optional and capped at 500 characters.\n\n### Response semantics\nHTTP 200 returns `resourceType: PaymentPlan`, `externalRisk: LOCAL_ONLY`, and operation-result status equal to the requested status when supplied or UPDATED otherwise. It does not create new scheduled payments or process patient payments.\n\n### Response notes\n- Cancellation updates pending scheduled payments to CANCELLED.\n- The response is an acknowledgement, not a full plan detail body.\n- Payment collection remains outside this endpoint.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization plan. Re-read plan and schedule state after timeouts before retrying cancellation or installment changes.\n\n### Error notes\n- 400 can indicate invalid status or date format.\n- 404 can intentionally hide wrong-tenant plans.\n- Retry only after checking whether the prior update completed.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"planId","in":"path","description":"Payment plan identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["DRAFT","ACTIVE","COMPLETED","CANCELLED","DEFAULTED","ON_HOLD"],"description":"Optional target payment-plan status."},"installmentAmount":{"type":"number","exclusiveMinimum":0,"description":"Optional new positive installment amount."},"nextPaymentDate":{"type":"string","format":"date-time","description":"Optional ISO date-time for the next scheduled payment."},"cancelReason":{"type":"string","minLength":1,"maxLength":500,"description":"Optional cancellation reason capped at 500 characters."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker stored in local metadata."}}},"example":{"status":"DRAFT","installmentAmount":125.5,"nextPaymentDate":"2026-06-08T10:15:30Z","cancelReason":"example-cancelreason","idempotencyKey":"example-idempotencykey"}}},"description":"Send `planId` in the path and any editable fields in the body. If `status` is CANCELLED, the handler cancels pending scheduled payments for that plan in the same organization."},"responses":{"200":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/statements":{"post":{"operationId":"createPatientArStatement","summary":"Create patient AR statement draft","description":"Creates a local Patient AR statement draft for an organization-scoped account.\n\n### When to use\nUse this when an external workflow needs QuickRCM to store statement draft metadata before separate PDF generation or delivery workflows.\n\n### Before calling\nResolve the account and current balance in the same tenant. Choose statement and due dates when the defaults are not sufficient.\n\n### Request guidance\n`accountId` and `idempotencyKey` are required. `statementDate`, `dueDate`, `deliveryMethod`, and `notes` are optional. Supplying `deliveryMethod` records draft metadata only; it does not send email, mail, fax, portal notification, or SMS.\n\n### Request notes\n- `idempotencyKey` is required and capped at 128 characters.\n- `deliveryMethod` accepts EMAIL, MAIL, PORTAL, FAX, or SMS but does not trigger delivery.\n- Keep statement notes free of unnecessary PHI and credentials.\n\n### Response semantics\nHTTP 201 returns `resourceType: Statement`, `status: DRAFT`, and `externalRisk: LOCAL_ONLY`. The handler sets deliveryStatus DRAFT, copies the current balance into previousBalance and totalDue, and sets new charges, payments, and adjustments to zero for the draft.\n\n### Response notes\n- `status: DRAFT` means local draft state only.\n- No PDF or delivery artifact is generated by this public endpoint.\n- The public response does not include the full statement body.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization account. After a timeout, inspect statement records before retrying because duplicate drafts are possible.\n\n### Error notes\n- 400 can indicate invalid dates or delivery method.\n- 404 means the account was not found in the API key organization.\n- Do not treat a created draft as delivered.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","minLength":1,"description":"Patient AR account identifier for the statement draft."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Required caller marker used in local metadata and generated statement number."},"statementDate":{"type":"string","format":"date-time","description":"Optional ISO date-time for the statement date; defaults to current time in the handler."},"dueDate":{"type":"string","format":"date-time","description":"Optional ISO date-time for payment due date."},"deliveryMethod":{"type":"string","enum":["EMAIL","MAIL","PORTAL","FAX","SMS"],"description":"Optional intended delivery channel recorded on the draft."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional statement note capped at 2000 characters."}},"required":["accountId","idempotencyKey"]},"example":{"accountId":"00000000-0000-4000-8000-000000000001","idempotencyKey":"example-idempotencykey","statementDate":"2026-06-08T10:15:30Z","dueDate":"2026-06-08T10:15:30Z","deliveryMethod":"EMAIL","notes":"Example patient_ar_statement note"}}},"description":"`accountId` and `idempotencyKey` are required. `statementDate`, `dueDate`, `deliveryMethod`, and `notes` are optional. Supplying `deliveryMethod` records draft metadata only; it does not send email, mail, fax, portal notification, or SMS."},"responses":{"201":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/deposit-batches":{"post":{"operationId":"createPatientArDepositBatch","summary":"Create patient AR deposit batch","description":"Creates a local deposit batch for cash/check-style Patient AR reconciliation in the authenticated organization.\n\n### When to use\nUse this before posting local payments that should be grouped into a reconciliation batch, or when an external workflow needs QuickRCM to track an expected deposit amount.\n\n### Before calling\nChoose the deposit date, expected amount, and stable idempotency key. Confirm this is local reconciliation metadata, not a bank deposit instruction.\n\n### Request guidance\n`idempotencyKey`, ISO `depositDate`, and nonnegative `expectedAmount` are required. `notes` is optional and should stay operational.\n\n### Request notes\n- `expectedAmount` can be zero or greater.\n- `depositDate` must be an ISO date-time.\n- This endpoint does not initiate bank transfer or lockbox processing.\n\n### Response semantics\nHTTP 201 returns `resourceType: DepositBatch`, `status: OPEN`, and `externalRisk: LOCAL_ONLY`. The handler sets actual amount and variance to zero and records the opener.\n\n### Response notes\n- Actual amount and variance are populated when the batch is closed.\n- The public response does not include full batch detail.\n\n### Errors and retries\nFix invalid date or amount after 400. After timeout, inspect open deposit batches before retrying to avoid duplicate batches.\n\n### Error notes\n- 400 means validation failed.\n- 429 should be retried with backoff.\n- Check local batch state after write timeouts.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Required caller marker used in local metadata and generated batch number."},"depositDate":{"type":"string","format":"date-time","description":"ISO date-time for the local deposit batch."},"expectedAmount":{"type":["number","null"],"minimum":0,"description":"Expected reconciliation amount for the batch."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional batch note capped at 2000 characters."}},"required":["idempotencyKey","depositDate","expectedAmount"]},"example":{"idempotencyKey":"example-idempotencykey","depositDate":"2026-06-08T10:15:30Z","expectedAmount":125.5,"notes":"Example patient_ar_deposit_batch note"}}},"description":"`idempotencyKey`, ISO `depositDate`, and nonnegative `expectedAmount` are required. `notes` is optional and should stay operational."},"responses":{"201":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/deposit-batches/{batchId}/close":{"post":{"operationId":"closePatientArDepositBatch","summary":"Close patient AR deposit batch","description":"Closes a local deposit batch and records actual amount, variance, closure metadata, and balanced/unbalanced status.\n\n### When to use\nUse this after reconciling the actual collected amount against the expected deposit batch amount.\n\n### Before calling\nResolve the target batch in the same tenant and calculate or verify the actual amount from local reconciliation evidence. The current handler looks up the batch by ID and organization; it does not enforce an OPEN-only precondition.\n\n### Request guidance\n`actualAmount` is required and nonnegative. The handler computes `variance` as actual amount minus expected amount, then sets status BALANCED when variance is zero and UNBALANCED otherwise.\n\n### Request notes\n- `actualAmount` can be zero or greater.\n- `idempotencyKey` is optional and stored in local metadata.\n\n### Response semantics\nHTTP 200 returns `resourceType: DepositBatch`, status BALANCED or UNBALANCED, and `externalRisk: LOCAL_ONLY`. It does not move money or update external bank records.\n\n### Response notes\n- BALANCED means actual amount equals expected amount in local records.\n- UNBALANCED means local actual and expected amounts differ.\n- The response is reconciliation metadata, not bank confirmation.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization batch. Re-read batch state after timeouts before retrying closure.\n\n### Error notes\n- 404 can mean the batch is outside the authenticated organization.\n- 400 can indicate invalid actual amount.\n- Avoid duplicate close attempts without reading current batch state.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"batchId","in":"path","description":"Deposit batch identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"actualAmount":{"type":["number","null"],"minimum":0,"description":"Actual reconciled amount for the local batch."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional closure note capped at 2000 characters."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker stored in local metadata."}},"required":["actualAmount"]},"example":{"actualAmount":125.5,"notes":"Example close_patient_ar_deposit_batch note","idempotencyKey":"example-idempotencykey"}}},"description":"`actualAmount` is required and nonnegative. The handler computes `variance` as actual amount minus expected amount, then sets status BALANCED when variance is zero and UNBALANCED otherwise."},"responses":{"200":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/collection-tasks":{"post":{"operationId":"createPatientArCollectionTask","summary":"Create patient AR collection task","description":"Creates a local PENDING collection task for an organization-scoped Patient AR account.\n\n### When to use\nUse this to create staff work around patient balance follow-up, promise follow-up, payment-plan offers, final notices, agency review, or write-off review.\n\n### Before calling\nResolve the account and optional assignee. If `assignedToId` is supplied, it must identify an active organization member.\n\n### Request guidance\n`accountId` and `taskType` are required. `priority` defaults to NORMAL. `dueDate` and `scheduledContactTime` must be ISO date-times when supplied. Keep notes operational and PHI-minimal.\n\n### Request notes\n- `taskType` accepts INITIAL_CONTACT, FOLLOW_UP, PROMISE_FOLLOW, PAYMENT_PLAN_OFFER, FINAL_NOTICE, AGENCY_REVIEW, or WRITE_OFF_REVIEW.\n- `priority` accepts LOW, NORMAL, HIGH, or URGENT.\n- `assignedToId` must be an active member of the same organization when supplied.\n\n### Response semantics\nHTTP 201 returns `resourceType: CollectionTask`, `status: PENDING`, and `externalRisk: LOCAL_ONLY`. It creates a local task only and does not contact the patient, send letters, assign an external agency, or take legal action.\n\n### Response notes\n- New tasks start PENDING.\n- No external communication is sent by this endpoint.\n- Use logPatientArCollectionActivity to record contact attempts and outcomes.\n\n### Errors and retries\nTreat 404 as missing account or assignee in the authenticated organization. After timeouts, inspect internal task state before recreating.\n\n### Error notes\n- 404 can mean the account or assignee is unavailable to this tenant.\n- 400 can indicate invalid enum or date values.\n- Do not document task creation as patient contact.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","minLength":1,"description":"Patient AR account identifier for the collection task."},"taskType":{"type":"string","enum":["INITIAL_CONTACT","FOLLOW_UP","PROMISE_FOLLOW","PAYMENT_PLAN_OFFER","FINAL_NOTICE","AGENCY_REVIEW","WRITE_OFF_REVIEW"],"description":"Collection task category enum."},"priority":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"default":"NORMAL","description":"Task priority. Defaults to NORMAL."},"dueDate":{"type":"string","format":"date-time","description":"Optional ISO date-time deadline for the task."},"scheduledContactTime":{"type":"string","format":"date-time","description":"Optional ISO date-time when contact is scheduled."},"assignedToId":{"type":"string","minLength":1,"description":"Optional QuickRCM user identifier for an active organization member."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional task note capped at 2000 characters."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker stored in local metadata."}},"required":["accountId","taskType"]},"example":{"accountId":"00000000-0000-4000-8000-000000000001","taskType":"INITIAL_CONTACT","priority":"NORMAL","dueDate":"2026-06-08T10:15:30Z","scheduledContactTime":"2026-06-08T10:15:30Z","assignedToId":"00000000-0000-4000-8000-000000000001","notes":"Example patient_ar_collection_task note","idempotencyKey":"example-idempotencykey"}}},"description":"`accountId` and `taskType` are required. `priority` defaults to NORMAL. `dueDate` and `scheduledContactTime` must be ISO date-times when supplied. Keep notes operational and PHI-minimal."},"responses":{"201":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/collection-tasks/{taskId}":{"put":{"operationId":"updatePatientArCollectionTask","summary":"Update patient AR collection task","description":"Updates local status, outcome, priority, due date, promise-to-pay fields, and notes on an organization-scoped collection task.\n\n### When to use\nUse this to progress a collection task, record task outcome, update promised payment metadata, or mark the task completed or cancelled.\n\n### Before calling\nResolve the task under the authenticated organization and decide whether a separate activity log is also needed for contact history.\n\n### Request guidance\nSend `taskId` in the path and any editable fields in the body. If `status` is COMPLETED, the handler records completed-by and completed-at metadata.\n\n### Request notes\n- `status` accepts PENDING, IN_PROGRESS, COMPLETED, CANCELLED, or OVERDUE.\n- `outcome` accepts PAYMENT_RECEIVED, PROMISE_MADE, NO_CONTACT, REFUSED, DISPUTED, DECEASED, BANKRUPTCY, or OTHER.\n- Use logPatientArCollectionActivity for contact-attempt rollups.\n\n### Response semantics\nHTTP 200 returns `resourceType: CollectionTask`, `externalRisk: LOCAL_ONLY`, and status equal to the requested status or UPDATED. It updates the task record only; it does not create a collection activity row or send patient communication.\n\n### Response notes\n- COMPLETED status records completion metadata.\n- The response is an acknowledgement, not full task detail.\n- No external communication is triggered.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization task. Re-read task state after timeouts before retrying status changes.\n\n### Error notes\n- 400 can indicate invalid enum, amount, or date values.\n- 404 can hide wrong-tenant task IDs.\n- Do not retry status updates blindly after timeout.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"taskId","in":"path","description":"Collection task identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","IN_PROGRESS","COMPLETED","CANCELLED","OVERDUE"],"description":"Optional target task status."},"outcome":{"type":"string","enum":["PAYMENT_RECEIVED","PROMISE_MADE","NO_CONTACT","REFUSED","DISPUTED","DECEASED","BANKRUPTCY","OTHER"],"description":"Optional task outcome enum."},"priority":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"],"description":"Optional target priority."},"dueDate":{"type":"string","format":"date-time","description":"Optional ISO date-time deadline."},"promiseToPayDate":{"type":"string","format":"date-time","description":"Optional ISO date-time promised payment date."},"promiseToPayAmount":{"type":["number","null"],"minimum":0,"description":"Optional nonnegative promised payment amount."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional staff note capped at 2000 characters."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker stored in local metadata."}}},"example":{"status":"PENDING","outcome":"PAYMENT_RECEIVED","priority":"LOW","dueDate":"2026-06-08T10:15:30Z","promiseToPayDate":"2026-06-08T10:15:30Z","promiseToPayAmount":125.5,"notes":"Example patient_ar_collection_task note","idempotencyKey":"example-idempotencykey"}}},"description":"Send `taskId` in the path and any editable fields in the body. If `status` is COMPLETED, the handler records completed-by and completed-at metadata."},"responses":{"200":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/patient-ar/collection-tasks/{taskId}/activities":{"post":{"operationId":"logPatientArCollectionActivity","summary":"Log patient AR collection activity","description":"Logs a local collection activity on an organization-scoped collection task and updates the task contact rollup.\n\n### When to use\nUse this after a staff member or upstream workflow has completed a phone call, email, letter, text message, payment-plan action, payment receipt, adjustment, write-off, agency assignment, legal action, or other local collection event.\n\n### Before calling\nResolve the task in the same tenant. Prepare only the contact details and outcome needed for local auditability, using synthetic examples in docs.\n\n### Request guidance\n`activityType` is required. Optional contact name, phone, email, subject, notes, outcome, promise-to-pay fields, and duration should be minimized to what the collection record needs. `durationSeconds` must be 0 through 86400.\n\n### Request notes\n- `activityType` accepts PHONE_CALL, EMAIL, LETTER, TEXT_MESSAGE, PAYMENT_PLAN_CREATED, PAYMENT_PLAN_UPDATED, PAYMENT_RECEIVED, ADJUSTMENT_MADE, WRITE_OFF, AGENCY_ASSIGNED, LEGAL_ACTION, or OTHER.\n- Logging an EMAIL, LETTER, or TEXT_MESSAGE activity does not send that communication.\n- Contact fields can be PHI or sensitive financial context; examples must be synthetic.\n\n### Response semantics\nHTTP 201 returns `resourceType: CollectionActivity`, `status: CREATED`, and `externalRisk: LOCAL_ONLY`. The handler creates a local activity, increments task contact attempts, updates last contact timestamp/outcome, and records promise-to-pay rollups when supplied.\n\n### Response notes\n- The response is a local audit acknowledgement.\n- Task contact attempts are incremented by the handler.\n- Promise-to-pay fields update task rollups when supplied.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization task. Re-read activities or task rollup after timeouts before retrying because duplicate activity logs can affect contact counts.\n\n### Error notes\n- 400 can indicate invalid email, enum, duration, date, or amount values.\n- 404 can mean the task is unavailable to this organization.\n- Avoid duplicate logging after timeouts without checking current task activity.\n","tags":["Patient AR"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"taskId","in":"path","description":"Collection task identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"activityType":{"type":"string","enum":["PHONE_CALL","EMAIL","LETTER","TEXT_MESSAGE","PAYMENT_PLAN_CREATED","PAYMENT_PLAN_UPDATED","PAYMENT_RECEIVED","ADJUSTMENT_MADE","WRITE_OFF","AGENCY_ASSIGNED","LEGAL_ACTION","OTHER"],"description":"Required collection activity type enum."},"channel":{"type":"string","minLength":1,"maxLength":80,"description":"Optional channel label capped at 80 characters."},"direction":{"type":"string","minLength":1,"maxLength":80,"description":"Optional direction label capped at 80 characters."},"outcome":{"type":"string","enum":["PAYMENT_RECEIVED","PROMISE_MADE","NO_CONTACT","REFUSED","DISPUTED","DECEASED","BANKRUPTCY","OTHER"],"description":"Optional collection outcome enum."},"contactName":{"type":"string","minLength":1,"maxLength":200,"description":"Optional contact display name. Treat as PHI-sensitive when tied to a patient account."},"contactPhone":{"type":"string","minLength":1,"maxLength":80,"description":"Optional contact phone. Use synthetic values in examples."},"contactEmail":{"type":"string","format":"email","description":"Optional contact email. Must be a valid email format."},"promiseToPayDate":{"type":"string","format":"date-time","description":"Optional ISO date-time promised payment date."},"promiseToPayAmount":{"type":["number","null"],"minimum":0,"description":"Optional nonnegative promised payment amount."},"subject":{"type":"string","minLength":1,"maxLength":200,"description":"Optional activity subject capped at 200 characters."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional activity note capped at 2000 characters."},"durationSeconds":{"type":["integer","null"],"minimum":0,"maximum":86400,"description":"Optional activity duration from 0 through 86400 seconds."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller marker stored in local metadata."}},"required":["activityType"]},"example":{"activityType":"PHONE_CALL","channel":"example-channel","direction":"example-direction","outcome":"PAYMENT_RECEIVED","contactName":"Example log_patient_ar_collection_activity","contactPhone":"+15551234567","contactEmail":"developer@example.com","promiseToPayDate":"2026-06-08T10:15:30Z","promiseToPayAmount":125.5}}},"description":"`activityType` is required. Optional contact name, phone, email, subject, notes, outcome, promise-to-pay fields, and duration should be minimized to what the collection record needs. `durationSeconds` must be 0 through 86400."},"responses":{"201":{"description":"Patient AR public API operation completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"status":{"type":"string"},"externalRisk":{"type":"string","enum":["LOCAL_ONLY","QUEUED_ONLY","SIMULATED_ONLY"]}},"required":["resourceType","status"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"resourceType":"example-resourcetype","status":"active","id":"00000000-0000-4000-8000-000000000001","externalRisk":"LOCAL_ONLY"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller or RBAC denies access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested patient AR resource not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications":{"get":{"operationId":"listPayerEnrollmentApplications","summary":"List payer enrollment applications","description":"Lists active payer enrollment applications owned by the organization selected by the bearer API key.\n\n### When to use\nUse this endpoint to build payer enrollment worklists, filter applications by provider, payer, application status, or application type, and locate an application before retrieving detail or recording workflow activity.\n\n### Before calling\nAuthenticate with an API key that has `payer-enrollment:read` or `payer-enrollment:write` scope. Resolve optional `providerId` and `payerConfigId` from QuickRCM in the same organization.\n\n### Request guidance\n`skip` defaults to 0 and is capped at 10000; `take` defaults to 25 and is capped at 100. `status` must be a payer enrollment application status, and `applicationType` must be one of the public application type enum values. Do not send `organizationId`; the API key supplies tenant context.\n\n### Request notes\n- Use filters to keep result sets narrow because provider and payer enrollment data is sensitive operational context.\n- Only active application rows are returned by the current handler.\n- Use `getPayerEnrollmentApplication` for one application detail.\n- Results are ordered by `updatedAt` descending by current handler behavior.\n\n### Response semantics\nHTTP 200 returns `data.applications`, `total`, `skip`, `take`, and `meta.organizationId`. Each application includes local provider summary, payer configuration summary, form-template summary, lifecycle dates, follow-up count, assignment id, and local status. It is not evidence that a payer accepted, acknowledged, approved, or denied an enrollment unless the local status has been updated accordingly. Current handler behavior orders results by `updatedAt` descending.\n\n### Response notes\n- `provider`, `payerConfig`, and `formTemplate` are nullable summaries.\n- `organizationId` may appear in resource rows and `meta`, but callers should not use it as an input selector.\n- Lifecycle dates are ISO datetimes or null.\n\n### Errors and retries\nTreat 400 as invalid filters or pagination, 401 as missing or invalid bearer credentials, 403 as insufficient scope or tenant authorization failure, and 429 as a backoff signal. Retry transient 5xx responses with bounded backoff.\n\n### Error notes\n- 400 can indicate an invalid enum, negative skip, skip above 10000, or take above 100.\n- 429 should be retried with backoff, not tight polling.\n- 401 and 403 require credential, scope, or tenant-context correction.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":false,"name":"providerId","in":"query","description":"Optional provider enrollment profile identifier filter scoped to the API key organization."},{"schema":{"type":"string","minLength":1},"required":false,"name":"payerConfigId","in":"query","description":"Optional payer configuration identifier filter scoped to the API key organization."},{"schema":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"]},"required":false,"name":"status","in":"query","description":"Optional local payer enrollment application status filter."},{"schema":{"type":"string","enum":["INITIAL","REVALIDATION","CHANGE_OF_INFO","ADD_LOCATION","TERMINATION","REINSTATEMENT"]},"required":false,"name":"applicationType","in":"query","description":"Optional application type filter: INITIAL, REVALIDATION, CHANGE_OF_INFO, ADD_LOCATION, TERMINATION, or REINSTATEMENT."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"skip","in":"query","description":"Zero-based row offset. Defaults to 0 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"take","in":"query","description":"Maximum rows to return. Defaults to 25 and cannot exceed 100."}],"responses":{"200":{"description":"Payer enrollment applications for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"applications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"providerId":{"type":"string"},"provider":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"npi":{"type":"string"}},"required":["id","firstName","lastName","npi"]},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"applicationType":{"type":"string","enum":["INITIAL","REVALIDATION","CHANGE_OF_INFO","ADD_LOCATION","TERMINATION","REINSTATEMENT"]},"applicationMethod":{"type":"string","enum":["CAQH","PAYER_PORTAL","PAPER","EDI","PECOS"]},"payerApplicationId":{"type":["string","null"]},"caqhProviderId":{"type":["string","null"]},"status":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"]},"submissionDate":{"type":["string","null"],"format":"date-time"},"acknowledgmentDate":{"type":["string","null"],"format":"date-time"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"expirationDate":{"type":["string","null"],"format":"date-time"},"nextFollowUpDate":{"type":["string","null"],"format":"date-time"},"followUpCount":{"type":"integer","minimum":0},"estimatedProcessingDays":{"type":["integer","null"]},"assignedToId":{"type":["string","null"]},"formTemplateId":{"type":["string","null"]},"formTemplate":{"type":["object","null"],"properties":{"id":{"type":"string"},"formName":{"type":"string"},"formVersion":{"type":["string","null"]}},"required":["id","formName","formVersion"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","providerId","provider","payerConfigId","payerConfig","applicationType","applicationMethod","payerApplicationId","caqhProviderId","status","submissionDate","acknowledgmentDate","effectiveDate","expirationDate","nextFollowUpDate","followUpCount","estimatedProcessingDays","assignedToId","formTemplateId","formTemplate","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["applications","total","skip","take"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"applications":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","provider":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","npi":"1234567893"},"payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example payer_enrollment_application","payerId":"87726"},"applicationType":"INITIAL","applicationMethod":"CAQH","payerApplicationId":"00000000-0000-4000-8000-000000000001","caqhProviderId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","submissionDate":"2026-06-08T10:15:30Z","acknowledgmentDate":"2026-06-08T10:15:30Z","effectiveDate":"2026-06-08T10:15:30Z","expirationDate":"2026-06-08T10:15:30Z","nextFollowUpDate":"2026-06-08T10:15:30Z","followUpCount":1,"estimatedProcessingDays":1,"assignedToId":"00000000-0000-4000-8000-000000000001","formTemplateId":"00000000-0000-4000-8000-000000000001","formTemplate":{"id":"00000000-0000-4000-8000-000000000001","formName":"Example payer_enrollment_application","formVersion":"example-formversion"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"skip":1,"take":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createPayerEnrollmentApplication","summary":"Create payer enrollment application","description":"Creates a local DRAFT payer enrollment application for an organization-owned provider profile and payer configuration.\n\n### When to use\nUse this when a provider profile and payer configuration already exist in QuickRCM and the integration needs to start an enrollment, revalidation, change-of-information, location, termination, or reinstatement workflow.\n\n### Before calling\nResolve `providerId` from Payer Enrollment provider profiles and `payerConfigId` from the organization's payer configuration. Choose the `applicationType` and `applicationMethod` that match the intended workflow.\n\n### Request guidance\n`providerId`, `payerConfigId`, `applicationType`, and `applicationMethod` are required. The handler rejects duplicate active applications for the same organization, provider, payer, and application type by checking active database rows and non-terminal workflow statuses. It can attach an active form template by payer name when one exists for the organization or globally.\n\n### Request notes\n- `applicationMethod` describes the intended application channel; it does not trigger submission.\n- Duplicate detection searches rows with `status_field: ACTIVE` and ignores inactive terminal workflow statuses DENIED, WITHDRAWN, EXPIRED, and TERMINATED.\n- The created record receives a local status-history entry.\n\n### Response semantics\nHTTP 201 returns the created local application with status DRAFT and `meta.organizationId`. This endpoint does not submit the application to Council for Affordable Quality Healthcare (CAQH), a payer portal, Electronic Data Interchange (EDI), the Provider Enrollment, Chain, and Ownership System (PECOS), paper mail, or any external destination.\n\n### Response notes\n- Status is DRAFT on creation.\n- The response can include a matched form template summary.\n- No external payer or Council for Affordable Quality Healthcare (CAQH) acknowledgement is implied.\n\n### Errors and retries\nTreat 404 as provider profile or payer configuration not found in the authenticated organization. Treat 409 as an active application already existing for the same provider, payer, and type. After a network timeout, list or search for an existing application before retrying.\n\n### Error notes\n- 404 can mean `providerId` or `payerConfigId` is not available to the API key organization.\n- 409 means an active duplicate application exists.\n- 400 means the body failed schema validation.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"type":"string","minLength":1,"description":"Required provider enrollment profile identifier owned by the authenticated organization."},"payerConfigId":{"type":"string","minLength":1,"description":"Required organization-scoped payer configuration identifier."},"applicationType":{"type":"string","enum":["INITIAL","REVALIDATION","CHANGE_OF_INFO","ADD_LOCATION","TERMINATION","REINSTATEMENT"],"description":"Required workflow type: INITIAL, REVALIDATION, CHANGE_OF_INFO, ADD_LOCATION, TERMINATION, or REINSTATEMENT."},"applicationMethod":{"type":"string","enum":["CAQH","PAYER_PORTAL","PAPER","EDI","PECOS"],"description":"Required intended submission channel: Council for Affordable Quality Healthcare (CAQH), PAYER_PORTAL, PAPER, Electronic Data Interchange (EDI), or Provider Enrollment, Chain, and Ownership System (PECOS)."}},"required":["providerId","payerConfigId","applicationType","applicationMethod"]},"example":{"providerId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","applicationType":"INITIAL","applicationMethod":"CAQH"}}},"description":"`providerId`, `payerConfigId`, `applicationType`, and `applicationMethod` are required. The handler rejects duplicate active applications for the same organization, provider, payer, and application type by checking active database rows and non-terminal workflow statuses. It can attach an active form template by payer name when one exists for the organization or globally."},"responses":{"201":{"description":"Payer enrollment application created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"application":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"providerId":{"type":"string"},"provider":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"npi":{"type":"string"}},"required":["id","firstName","lastName","npi"]},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"applicationType":{"type":"string","enum":["INITIAL","REVALIDATION","CHANGE_OF_INFO","ADD_LOCATION","TERMINATION","REINSTATEMENT"]},"applicationMethod":{"type":"string","enum":["CAQH","PAYER_PORTAL","PAPER","EDI","PECOS"]},"payerApplicationId":{"type":["string","null"]},"caqhProviderId":{"type":["string","null"]},"status":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"]},"submissionDate":{"type":["string","null"],"format":"date-time"},"acknowledgmentDate":{"type":["string","null"],"format":"date-time"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"expirationDate":{"type":["string","null"],"format":"date-time"},"nextFollowUpDate":{"type":["string","null"],"format":"date-time"},"followUpCount":{"type":"integer","minimum":0},"estimatedProcessingDays":{"type":["integer","null"]},"assignedToId":{"type":["string","null"]},"formTemplateId":{"type":["string","null"]},"formTemplate":{"type":["object","null"],"properties":{"id":{"type":"string"},"formName":{"type":"string"},"formVersion":{"type":["string","null"]}},"required":["id","formName","formVersion"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","providerId","provider","payerConfigId","payerConfig","applicationType","applicationMethod","payerApplicationId","caqhProviderId","status","submissionDate","acknowledgmentDate","effectiveDate","expirationDate","nextFollowUpDate","followUpCount","estimatedProcessingDays","assignedToId","formTemplateId","formTemplate","createdAt","updatedAt"]}},"required":["application"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"application":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","provider":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","npi":"1234567893"},"payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example payer_enrollment_application","payerId":"87726"},"applicationType":"INITIAL","applicationMethod":"CAQH","payerApplicationId":"00000000-0000-4000-8000-000000000001","caqhProviderId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","submissionDate":"2026-06-08T10:15:30Z","acknowledgmentDate":"2026-06-08T10:15:30Z","effectiveDate":"2026-06-08T10:15:30Z","expirationDate":"2026-06-08T10:15:30Z","nextFollowUpDate":"2026-06-08T10:15:30Z","followUpCount":1,"estimatedProcessingDays":1,"assignedToId":"00000000-0000-4000-8000-000000000001","formTemplateId":"00000000-0000-4000-8000-000000000001","formTemplate":{"id":"00000000-0000-4000-8000-000000000001","formName":"Example payer_enrollment_application","formVersion":"example-formversion"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Provider profile or payer configuration not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"An active payer enrollment application already exists for the provider and payer.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications/{applicationId}":{"get":{"operationId":"getPayerEnrollmentApplication","summary":"Get payer enrollment application","description":"Returns one active payer enrollment application when it belongs to the authenticated organization.\n\n### When to use\nUse this after a list response, create response, clone response, assignment workflow, or internal queue gives you an `applicationId` from the same tenant.\n\n### Before calling\nUse an `applicationId` obtained from the same API-key organization context. Read access accepts `payer-enrollment:read` or `payer-enrollment:write` scope.\n\n### Request guidance\nPass `applicationId` in the path only. Do not include payer portal credentials, raw payer payloads, or organization selectors.\n\n### Request notes\n- Use an application id returned by QuickRCM for this tenant.\n- No request body or query parameters are declared.\n- Wrong-tenant resources should be documented as not available to the caller.\n\n### Response semantics\nHTTP 200 returns `data.application` with local provider, payer, form-template, status, assignment, lifecycle dates, and follow-up metadata. The response is local QuickRCM state and does not represent live payer portal state.\n\n### Response notes\n- `data.application.status` is the local application workflow status.\n- `payerApplicationId` and `caqhProviderId` can be null.\n- `provider`, `payerConfig`, and `formTemplate` can be null if related summary data is unavailable.\n\n### Errors and retries\nTreat 404 as missing, inactive, or wrong-organization application context unless a prior trusted response proves the application exists. Retry only transient 5xx and 429 responses with backoff.\n\n### Error notes\n- 404 can intentionally hide wrong-organization records.\n- 401 and 403 require credential or scope correction.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"applicationId","in":"path","description":"QuickRCM payer enrollment application identifier in the path. It must resolve inside the API key organization."}],"responses":{"200":{"description":"Payer enrollment application detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"application":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"providerId":{"type":"string"},"provider":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"npi":{"type":"string"}},"required":["id","firstName","lastName","npi"]},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"applicationType":{"type":"string","enum":["INITIAL","REVALIDATION","CHANGE_OF_INFO","ADD_LOCATION","TERMINATION","REINSTATEMENT"]},"applicationMethod":{"type":"string","enum":["CAQH","PAYER_PORTAL","PAPER","EDI","PECOS"]},"payerApplicationId":{"type":["string","null"]},"caqhProviderId":{"type":["string","null"]},"status":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"]},"submissionDate":{"type":["string","null"],"format":"date-time"},"acknowledgmentDate":{"type":["string","null"],"format":"date-time"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"expirationDate":{"type":["string","null"],"format":"date-time"},"nextFollowUpDate":{"type":["string","null"],"format":"date-time"},"followUpCount":{"type":"integer","minimum":0},"estimatedProcessingDays":{"type":["integer","null"]},"assignedToId":{"type":["string","null"]},"formTemplateId":{"type":["string","null"]},"formTemplate":{"type":["object","null"],"properties":{"id":{"type":"string"},"formName":{"type":"string"},"formVersion":{"type":["string","null"]}},"required":["id","formName","formVersion"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","providerId","provider","payerConfigId","payerConfig","applicationType","applicationMethod","payerApplicationId","caqhProviderId","status","submissionDate","acknowledgmentDate","effectiveDate","expirationDate","nextFollowUpDate","followUpCount","estimatedProcessingDays","assignedToId","formTemplateId","formTemplate","createdAt","updatedAt"]}},"required":["application"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"application":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","provider":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","npi":"1234567893"},"payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example payer_enrollment_application","payerId":"87726"},"applicationType":"INITIAL","applicationMethod":"CAQH","payerApplicationId":"00000000-0000-4000-8000-000000000001","caqhProviderId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","submissionDate":"2026-06-08T10:15:30Z","acknowledgmentDate":"2026-06-08T10:15:30Z","effectiveDate":"2026-06-08T10:15:30Z","expirationDate":"2026-06-08T10:15:30Z","nextFollowUpDate":"2026-06-08T10:15:30Z","followUpCount":1,"estimatedProcessingDays":1,"assignedToId":"00000000-0000-4000-8000-000000000001","formTemplateId":"00000000-0000-4000-8000-000000000001","formTemplate":{"id":"00000000-0000-4000-8000-000000000001","formName":"Example payer_enrollment_application","formVersion":"example-formversion"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Payer enrollment application not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"updatePayerEnrollmentApplication","summary":"Update payer enrollment application field","description":"Updates one field in the local application data object for an active organization-scoped payer enrollment application.\n\n### When to use\nUse this for controlled manual corrections to a payer enrollment application's structured form data before review or submission validation.\n\n### Before calling\nLoad the application for the same tenant and choose a `fieldId` that your integration understands. Prepare a JSON-serializable `value` and keep it free of credentials, tokens, raw payer responses, and unnecessary Protected Health Information (PHI).\n\n### Request guidance\n`fieldId` is required and capped at 200 characters. `value` is schema-open but the serialized JSON value cannot exceed 10000 characters. The current handler does not validate `fieldId` against the payer form template; public docs should describe it as caller/application-data specific.\n\n### Request notes\n- `value` must be JSON-serializable and below the server's serialized size limit.\n- Use only documented or internally agreed field ids; the public schema does not enumerate payer form fields.\n- Do not send raw payer portal payloads or credentials as field values.\n\n### Response semantics\nHTTP 200 returns the updated local application shell. If a previous value existed and changed, the handler appends a local manual override entry internally, but manual override details are not exposed in the public response.\n\n### Response notes\n- The public response returns application summary fields, not the full `applicationData` payload.\n- Manual override audit details are internal.\n- Related provider summary may be null in mutation responses when it is not reloaded.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization application. Treat 400 as invalid `fieldId` or oversized field value. After timeouts, re-read the application before retrying because repeated updates can overwrite the same field.\n\n### Error notes\n- 400 can indicate `fieldId` is empty or the serialized value exceeds 10000 characters.\n- 404 can indicate the application is missing, inactive, or outside the tenant.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"applicationId","in":"path","description":"QuickRCM payer enrollment application identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fieldId":{"type":"string","minLength":1,"maxLength":200,"description":"Caller/application-specific local form field identifier to update. It is not validated against a public template schema by this endpoint."},"value":{"description":"JSON value to store for the field. Serialized size must be at most 10000 characters."}},"required":["fieldId"]},"example":{"fieldId":"00000000-0000-4000-8000-000000000001","value":"example-value"}}},"description":"`fieldId` is required and capped at 200 characters. `value` is schema-open but the serialized JSON value cannot exceed 10000 characters. The current handler does not validate `fieldId` against the payer form template; public docs should describe it as caller/application-data specific."},"responses":{"200":{"description":"Payer enrollment application updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"application":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"providerId":{"type":"string"},"provider":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"npi":{"type":"string"}},"required":["id","firstName","lastName","npi"]},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"applicationType":{"type":"string","enum":["INITIAL","REVALIDATION","CHANGE_OF_INFO","ADD_LOCATION","TERMINATION","REINSTATEMENT"]},"applicationMethod":{"type":"string","enum":["CAQH","PAYER_PORTAL","PAPER","EDI","PECOS"]},"payerApplicationId":{"type":["string","null"]},"caqhProviderId":{"type":["string","null"]},"status":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"]},"submissionDate":{"type":["string","null"],"format":"date-time"},"acknowledgmentDate":{"type":["string","null"],"format":"date-time"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"expirationDate":{"type":["string","null"],"format":"date-time"},"nextFollowUpDate":{"type":["string","null"],"format":"date-time"},"followUpCount":{"type":"integer","minimum":0},"estimatedProcessingDays":{"type":["integer","null"]},"assignedToId":{"type":["string","null"]},"formTemplateId":{"type":["string","null"]},"formTemplate":{"type":["object","null"],"properties":{"id":{"type":"string"},"formName":{"type":"string"},"formVersion":{"type":["string","null"]}},"required":["id","formName","formVersion"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","providerId","provider","payerConfigId","payerConfig","applicationType","applicationMethod","payerApplicationId","caqhProviderId","status","submissionDate","acknowledgmentDate","effectiveDate","expirationDate","nextFollowUpDate","followUpCount","estimatedProcessingDays","assignedToId","formTemplateId","formTemplate","createdAt","updatedAt"]}},"required":["application"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"application":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","provider":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","npi":"1234567893"},"payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example payer_enrollment_application","payerId":"87726"},"applicationType":"INITIAL","applicationMethod":"CAQH","payerApplicationId":"00000000-0000-4000-8000-000000000001","caqhProviderId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","submissionDate":"2026-06-08T10:15:30Z","acknowledgmentDate":"2026-06-08T10:15:30Z","effectiveDate":"2026-06-08T10:15:30Z","expirationDate":"2026-06-08T10:15:30Z","nextFollowUpDate":"2026-06-08T10:15:30Z","followUpCount":1,"estimatedProcessingDays":1,"assignedToId":"00000000-0000-4000-8000-000000000001","formTemplateId":"00000000-0000-4000-8000-000000000001","formTemplate":{"id":"00000000-0000-4000-8000-000000000001","formName":"Example payer_enrollment_application","formVersion":"example-formversion"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Payer enrollment application not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications/{applicationId}/status":{"put":{"operationId":"updatePayerEnrollmentApplicationStatus","summary":"Update payer enrollment application status","description":"Applies a valid local status transition to an active payer enrollment application.\n\n### When to use\nUse this to move an application through QuickRCM's local enrollment workflow after staff review, payer feedback, or validated automation evidence.\n\n### Before calling\nRead the current application status and confirm the requested `newStatus` is allowed from that state. Prepare an optional concise `note` for status history.\n\n### Request guidance\n`newStatus` is required and must be one of the application status enum values. The handler enforces these transitions in addition to enum validation: DRAFT -> AUTO_FILLING, READY_FOR_REVIEW, PENDING_DOCUMENTS, WITHDRAWN; AUTO_FILLING -> READY_FOR_REVIEW, DRAFT; READY_FOR_REVIEW -> SUBMITTED, PENDING_DOCUMENTS, DRAFT, WITHDRAWN; PENDING_DOCUMENTS -> READY_FOR_REVIEW, SUBMITTED, WITHDRAWN; SUBMITTED -> ACKNOWLEDGED, IN_REVIEW, DEFICIENCY_RECEIVED, APPROVED, DENIED, WITHDRAWN; ACKNOWLEDGED -> IN_REVIEW, DEFICIENCY_RECEIVED, APPROVED, DENIED; IN_REVIEW -> DEFICIENCY_RECEIVED, APPROVED, DENIED; DEFICIENCY_RECEIVED -> DEFICIENCY_RESOLVED, DENIED, WITHDRAWN; DEFICIENCY_RESOLVED -> IN_REVIEW, APPROVED, DENIED; APPROVED -> EFFECTIVE, WITHDRAWN; EFFECTIVE -> EXPIRED, TERMINATED; EXPIRED -> DRAFT; TERMINATED -> DRAFT. DENIED and WITHDRAWN have no outbound transitions.\n\n### Request notes\n- Allowed transitions are enforced by current status, not just by enum membership.\n- DENIED and WITHDRAWN are terminal in the current public handler; EXPIRED and TERMINATED can reopen only to DRAFT.\n- `note` is optional and capped at 1000 characters.\n- Use this for local workflow tracking; do not present it as external payer confirmation.\n\n### Response semantics\nHTTP 200 returns the updated local application summary and `meta.organizationId`. A transition to APPROVED currently sets `effectiveDate` to the server timestamp. The response is local status state, not payer portal proof.\n\n### Response notes\n- The response returns the updated application summary.\n- Status-history details are not exposed in the public response.\n- APPROVED currently also stamps `effectiveDate`.\n\n### Errors and retries\nTreat 400 as invalid transition or invalid body. Treat 404 as missing, inactive, or wrong-organization application. After timeouts, re-read the application before retrying to avoid applying a stale transition.\n\n### Error notes\n- 400 can include an invalid transition message.\n- 404 means the application was not found in active tenant scope.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"applicationId","in":"path","description":"QuickRCM payer enrollment application identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"newStatus":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"],"description":"Required target local application status. It must be reachable from the current status according to the documented transition graph."},"note":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional status-history note. Keep it concise and avoid sensitive payloads."}},"required":["newStatus"]},"example":{"newStatus":"DRAFT","note":"Example payer_enrollment_application_statu note"}}},"description":"`newStatus` is required and must be one of the application status enum values. The handler enforces these transitions in addition to enum validation: DRAFT -> AUTO_FILLING, READY_FOR_REVIEW, PENDING_DOCUMENTS, WITHDRAWN; AUTO_FILLING -> READY_FOR_REVIEW, DRAFT; READY_FOR_REVIEW -> SUBMITTED, PENDING_DOCUMENTS, DRAFT, WITHDRAWN; PENDING_DOCUMENTS -> READY_FOR_REVIEW, SUBMITTED, WITHDRAWN; SUBMITTED -> ACKNOWLEDGED, IN_REVIEW, DEFICIENCY_RECEIVED, APPROVED, DENIED, WITHDRAWN; ACKNOWLEDGED -> IN_REVIEW, DEFICIENCY_RECEIVED, APPROVED, DENIED; IN_REVIEW -> DEFICIENCY_RECEIVED, APPROVED, DENIED; DEFICIENCY_RECEIVED -> DEFICIENCY_RESOLVED, DENIED, WITHDRAWN; DEFICIENCY_RESOLVED -> IN_REVIEW, APPROVED, DENIED; APPROVED -> EFFECTIVE, WITHDRAWN; EFFECTIVE -> EXPIRED, TERMINATED; EXPIRED -> DRAFT; TERMINATED -> DRAFT. DENIED and WITHDRAWN have no outbound transitions."},"responses":{"200":{"description":"Payer enrollment application status updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"application":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"providerId":{"type":"string"},"provider":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"npi":{"type":"string"}},"required":["id","firstName","lastName","npi"]},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"applicationType":{"type":"string","enum":["INITIAL","REVALIDATION","CHANGE_OF_INFO","ADD_LOCATION","TERMINATION","REINSTATEMENT"]},"applicationMethod":{"type":"string","enum":["CAQH","PAYER_PORTAL","PAPER","EDI","PECOS"]},"payerApplicationId":{"type":["string","null"]},"caqhProviderId":{"type":["string","null"]},"status":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"]},"submissionDate":{"type":["string","null"],"format":"date-time"},"acknowledgmentDate":{"type":["string","null"],"format":"date-time"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"expirationDate":{"type":["string","null"],"format":"date-time"},"nextFollowUpDate":{"type":["string","null"],"format":"date-time"},"followUpCount":{"type":"integer","minimum":0},"estimatedProcessingDays":{"type":["integer","null"]},"assignedToId":{"type":["string","null"]},"formTemplateId":{"type":["string","null"]},"formTemplate":{"type":["object","null"],"properties":{"id":{"type":"string"},"formName":{"type":"string"},"formVersion":{"type":["string","null"]}},"required":["id","formName","formVersion"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","providerId","provider","payerConfigId","payerConfig","applicationType","applicationMethod","payerApplicationId","caqhProviderId","status","submissionDate","acknowledgmentDate","effectiveDate","expirationDate","nextFollowUpDate","followUpCount","estimatedProcessingDays","assignedToId","formTemplateId","formTemplate","createdAt","updatedAt"]}},"required":["application"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"application":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","provider":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","npi":"1234567893"},"payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example payer_enrollment_application_statu","payerId":"87726"},"applicationType":"INITIAL","applicationMethod":"CAQH","payerApplicationId":"00000000-0000-4000-8000-000000000001","caqhProviderId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","submissionDate":"2026-06-08T10:15:30Z","acknowledgmentDate":"2026-06-08T10:15:30Z","effectiveDate":"2026-06-08T10:15:30Z","expirationDate":"2026-06-08T10:15:30Z","nextFollowUpDate":"2026-06-08T10:15:30Z","followUpCount":1,"estimatedProcessingDays":1,"assignedToId":"00000000-0000-4000-8000-000000000001","formTemplateId":"00000000-0000-4000-8000-000000000001","formTemplate":{"id":"00000000-0000-4000-8000-000000000001","formName":"Example payer_enrollment_application_statu","formVersion":"example-formversion"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Payer enrollment application not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications/{applicationId}/submit":{"post":{"operationId":"submitPayerEnrollmentApplication","summary":"Validate payer enrollment application submission","description":"Validates that an active application could move toward submitted workflow and returns a simulated-only submission response.\n\n### When to use\nUse this as a safe readiness check before building or enabling a separate payer portal, Council for Affordable Quality Healthcare (CAQH), Electronic Data Interchange (EDI), Provider Enrollment, Chain, and Ownership System (PECOS), or paper submission workflow outside the public API.\n\n### Before calling\nLoad the application and confirm its current status can transition to SUBMITTED. Send `validateOnly: true`; it is required by the public schema.\n\n### Request guidance\n`validateOnly` must be true. `submissionMethod` is optional and capped at 50 characters; the response defaults it to `manual` when omitted. `idempotencyKey` is accepted by the schema, but current handler evidence does not show server-side duplicate replay or dedupe because the endpoint performs no external submission.\n\n### Request notes\n- `validateOnly: true` is required.\n- The current public endpoint is simulated-only.\n- `idempotencyKey` should not contain Protected Health Information (PHI); current evidence does not show dedupe.\n\n### Response semantics\nHTTP 202 returns `data.mode: SIMULATED_ONLY`, the `applicationId`, selected `submissionMethod`, `wouldSubmit: true`, and `meta.smokeCategory: SIMULATED_ONLY`. It does not update application status and does not submit anything externally.\n\n### Response notes\n- `mode` and `meta.smokeCategory` are SIMULATED_ONLY.\n- `wouldSubmit: true` means the validation path passed, not that submission occurred.\n- No payer portal, Council for Affordable Quality Healthcare (CAQH), Electronic Data Interchange (EDI), Provider Enrollment, Chain, and Ownership System (PECOS), or paper submission side effect occurs.\n\n### Errors and retries\nTreat 400 as invalid body or application status that cannot submit. Treat 404 as missing or wrong-organization application. Retry transient 5xx and 429 with backoff; do not rely on `idempotencyKey` for dedupe behavior unless implementation changes.\n\n### Error notes\n- 400 can mean the current status cannot transition to SUBMITTED.\n- 404 can mean the application is not available in active tenant scope.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"applicationId","in":"path","description":"QuickRCM payer enrollment application identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"submissionMethod":{"type":"string","minLength":1,"maxLength":50,"description":"Optional caller label for the intended submission method; defaults to manual in the simulated response."},"validateOnly":{"type":"boolean","enum":[true],"description":"Required literal true safety flag for public submit validation."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker accepted by schema. Do not include Protected Health Information (PHI); current handler does not evidence dedupe."}},"required":["validateOnly"]},"example":{"validateOnly":true,"submissionMethod":"example-submissionmethod","idempotencyKey":"example-idempotencykey"}}},"description":"`validateOnly` must be true. `submissionMethod` is optional and capped at 50 characters; the response defaults it to `manual` when omitted. `idempotencyKey` is accepted by the schema, but current handler evidence does not show server-side duplicate replay or dedupe because the endpoint performs no external submission."},"responses":{"202":{"description":"Submission validation completed without external payer side effects.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY"]},"applicationId":{"type":"string"},"submissionMethod":{"type":"string"},"credentialingSessionId":{"type":"string"},"wouldSubmit":{"type":"boolean"},"wouldCreateProfile":{"type":"boolean"},"totalRows":{"type":"integer","minimum":0},"matchedProfiles":{"type":"integer","minimum":0},"matchedPayers":{"type":"integer","minimum":0},"errors":{"type":"array","items":{"type":"string"}}},"required":["mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"smokeCategory":{"type":"string","enum":["SIMULATED_ONLY"]}},"required":["organizationId","smokeCategory"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","applicationId":"00000000-0000-4000-8000-000000000001","submissionMethod":"example-submissionmethod","credentialingSessionId":"00000000-0000-4000-8000-000000000001","wouldSubmit":true,"wouldCreateProfile":true,"totalRows":1,"matchedProfiles":1,"matchedPayers":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","smokeCategory":"SIMULATED_ONLY"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Payer enrollment application not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications/{applicationId}/follow-ups":{"post":{"operationId":"recordPayerEnrollmentApplicationFollowUp","summary":"Record payer enrollment follow-up","description":"Records a local follow-up note for an active organization-scoped payer enrollment application and updates local follow-up counters on the application.\n\n### When to use\nUse this after staff or automation completes a portal check, phone call, email, fax, or internal note about an enrollment application.\n\n### Before calling\nConfirm the application exists in the same tenant. Prepare method, outcome, and optional notes, contact, next action, and next follow-up date. Do not include payer portal credentials, call transcripts, or raw payer payloads.\n\n### Request guidance\n`method` and `outcome` are required. `contactName` is optional local follow-up contact metadata capped at 200 characters; public examples must use synthetic names that are not Protected Health Information (PHI). `contactPhone` is normalized by stripping spaces, parentheses, periods, and hyphens, then validated as a US/international-like phone string. If `nextFollowUpDate` is omitted, the application receives a default next follow-up date 14 days after the current server time; the follow-up record response itself returns null for nextFollowUpDate when the request omitted it.\n\n### Request notes\n- `method` must be PORTAL_CHECK, PHONE, EMAIL, FAX, or INTERNAL_NOTE.\n- `outcome` is required and capped at 1000 characters.\n- Notes are operational; avoid unnecessary Protected Health Information (PHI), credentials, and raw vendor data.\n\n### Response semantics\nHTTP 201 returns the created follow-up summary: id, applicationId, method, outcome, notes, nextFollowUpDate, createdAt, and `meta.organizationId`. Contact name, phone, and next action are accepted inputs but not included in the public response schema.\n\n### Response notes\n- The response returns follow-up summary fields only.\n- Application `followUpCount` is incremented separately.\n- The default 14-day next-follow-up behavior is visible on the application update, not necessarily in the follow-up response.\n\n### Errors and retries\nTreat 400 as invalid body or phone format. Treat 404 as missing or wrong-organization application. After timeouts, re-read follow-up history or the application before retrying to avoid duplicate notes.\n\n### Error notes\n- 400 can indicate invalid phone number format.\n- 404 means the application is not available in active tenant scope.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"applicationId","in":"path","description":"QuickRCM payer enrollment application identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["PORTAL_CHECK","PHONE","EMAIL","FAX","INTERNAL_NOTE"],"description":"Required follow-up channel: PORTAL_CHECK, PHONE, EMAIL, FAX, or INTERNAL_NOTE."},"outcome":{"type":"string","minLength":1,"maxLength":1000,"description":"Required result summary of the follow-up interaction."},"notes":{"type":"string","minLength":1,"maxLength":4000,"description":"Optional staff note. Do not include portal credentials, raw payer payloads, or call transcripts."},"contactName":{"type":"string","minLength":1,"maxLength":200,"description":"Optional follow-up contact name capped at 200 characters. It is stored as local follow-up contact metadata and is not returned in the public follow-up response; public examples must use synthetic names that are not Protected Health Information (PHI)."},"contactPhone":{"type":"string","minLength":1,"maxLength":50,"description":"Optional contact phone string; the handler strips common punctuation and validates the remaining value."},"nextAction":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional next operational action. Accepted in the request but not returned in the follow-up response."},"nextFollowUpDate":{"type":"string","format":"date-time","description":"Optional ISO datetime for the next follow-up. If omitted, application-level next follow-up defaults to 14 days later."}},"required":["method","outcome"]},"example":{"method":"PORTAL_CHECK","outcome":"example-outcome","notes":"Example payer_enrollment_application_follow_up note","contactName":"Example payer_enrollment_application_follow_up","contactPhone":"+15551234567","nextAction":"example-nextaction","nextFollowUpDate":"2026-06-08T10:15:30Z"}}},"description":"`method` and `outcome` are required. `contactName` is optional local follow-up contact metadata capped at 200 characters; public examples must use synthetic names that are not Protected Health Information (PHI). `contactPhone` is normalized by stripping spaces, parentheses, periods, and hyphens, then validated as a US/international-like phone string. If `nextFollowUpDate` is omitted, the application receives a default next follow-up date 14 days after the current server time; the follow-up record response itself returns null for nextFollowUpDate when the request omitted it."},"responses":{"201":{"description":"Follow-up note recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"followUp":{"type":"object","properties":{"id":{"type":"string"},"applicationId":{"type":"string"},"method":{"type":"string","enum":["PORTAL_CHECK","PHONE","EMAIL","FAX","INTERNAL_NOTE"]},"outcome":{"type":"string"},"notes":{"type":["string","null"]},"nextFollowUpDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","applicationId","method","outcome","notes","nextFollowUpDate","createdAt"]}},"required":["followUp"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"followUp":{"id":"00000000-0000-4000-8000-000000000001","applicationId":"00000000-0000-4000-8000-000000000001","method":"PORTAL_CHECK","outcome":"example-outcome","notes":"Example payer_enrollment_application_follow_up note","nextFollowUpDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Payer enrollment application not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications/{applicationId}/deficiencies":{"post":{"operationId":"recordPayerEnrollmentApplicationDeficiency","summary":"Record payer enrollment deficiency","description":"Creates a local deficiency record for an active payer enrollment application and may move the application to DEFICIENCY_RECEIVED when that transition is valid.\n\n### When to use\nUse this when a payer, Council for Affordable Quality Healthcare (CAQH) workflow, staff review, or internal validation identifies missing or incorrect enrollment application information that needs resolution tracking.\n\n### Before calling\nConfirm the application exists in the same tenant. Prepare a concise deficiency type and description, and optional field reference, document requirement, and due date.\n\n### Request guidance\n`deficiencyType` and `description` are required. `fieldReference` can point to the affected local form/application field. `documentRequired` should name the requested document category rather than embedding document contents. `dueDate` must be an ISO datetime when provided.\n\n### Request notes\n- Use `fieldReference` for a local field identifier, not a raw payer payload path unless product defines it.\n- `documentRequired` is metadata only; do not upload file bytes here.\n- The application may be moved to DEFICIENCY_RECEIVED when allowed by its current status.\n\n### Response semantics\nHTTP 201 returns the created deficiency with status OPEN and `meta.organizationId`. If the application could validly transition to DEFICIENCY_RECEIVED, the handler updates the application separately; the deficiency response does not include the application.\n\n### Response notes\n- The returned deficiency status is OPEN.\n- Application status changes are side effects and not included in the response body.\n- Document contents and attachments are not handled by this endpoint.\n\n### Errors and retries\nTreat 400 as validation failure and 404 as missing or wrong-organization application. After timeouts, check for an existing deficiency before retrying to avoid duplicate deficiency records.\n\n### Error notes\n- 400 can indicate missing required deficiency fields or invalid datetime.\n- 404 means the application is not available in active tenant scope.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"applicationId","in":"path","description":"QuickRCM payer enrollment application identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deficiencyType":{"type":"string","minLength":1,"maxLength":200,"description":"Required local category or payer-reported deficiency type, capped at 200 characters."},"description":{"type":"string","minLength":1,"maxLength":4000,"description":"Required explanation of the deficiency, capped at 4000 characters."},"fieldReference":{"type":"string","minLength":1,"maxLength":200,"description":"Optional local field reference related to the deficiency."},"documentRequired":{"type":"string","minLength":1,"maxLength":500,"description":"Optional name of a requested document category; not file content."},"dueDate":{"type":"string","format":"date-time","description":"Optional ISO datetime by which the deficiency should be resolved."}},"required":["deficiencyType","description"]},"example":{"deficiencyType":"example-deficiencytype","description":"Example payer_enrollment_application_deficiency note","fieldReference":"example-fieldreference","documentRequired":"example-documentrequired","dueDate":"2026-06-08T10:15:30Z"}}},"description":"`deficiencyType` and `description` are required. `fieldReference` can point to the affected local form/application field. `documentRequired` should name the requested document category rather than embedding document contents. `dueDate` must be an ISO datetime when provided."},"responses":{"201":{"description":"Deficiency recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deficiency":{"type":"object","properties":{"id":{"type":"string"},"applicationId":{"type":"string"},"deficiencyType":{"type":"string"},"description":{"type":"string"},"fieldReference":{"type":["string","null"]},"documentRequired":{"type":["string","null"]},"status":{"type":"string"},"dueDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","applicationId","deficiencyType","description","fieldReference","documentRequired","status","dueDate","createdAt"]}},"required":["deficiency"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"deficiency":{"id":"00000000-0000-4000-8000-000000000001","applicationId":"00000000-0000-4000-8000-000000000001","deficiencyType":"example-deficiencytype","description":"Example payer_enrollment_application_deficiency note","fieldReference":"example-fieldreference","documentRequired":"example-documentrequired","status":"active","dueDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Payer enrollment application not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/deficiencies/{deficiencyId}/resolve":{"put":{"operationId":"resolvePayerEnrollmentDeficiency","summary":"Resolve payer enrollment deficiency","description":"Marks a local payer enrollment deficiency as RESOLVED when its parent application belongs to the authenticated organization.\n\n### When to use\nUse this after staff or automation has supplied the missing information or document evidence for an enrollment deficiency.\n\n### Before calling\nResolve `deficiencyId` from a deficiency returned or created in the same organization. Prepare a concise resolution note.\n\n### Request guidance\n`resolution` is required and capped at 4000 characters. The endpoint looks up the deficiency through an active organization-scoped parent application.\n\n### Request notes\n- Resolution text is an operational note; avoid raw payer payloads or credentials.\n- The endpoint checks remaining OPEN deficiencies before updating the application.\n- It does not upload or transmit supporting documents.\n\n### Response semantics\nHTTP 200 returns `deficiencyId`, status RESOLVED, `applicationStatusUpdated`, and `meta.organizationId`. If no other OPEN deficiencies remain and the parent application can move to DEFICIENCY_RESOLVED, `applicationStatusUpdated` is true.\n\n### Response notes\n- `applicationStatusUpdated` describes local application status side effect.\n- The full deficiency object is not returned.\n- The response is local workflow state only.\n\n### Errors and retries\nTreat 404 as missing deficiency, inactive parent application, or wrong tenant. After a timeout, re-read the deficiency/application state before retrying because the endpoint can update both deficiency and application status.\n\n### Error notes\n- 404 can mean the deficiency or its parent application is not accessible to the tenant.\n- 400 means the resolution body failed validation.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"deficiencyId","in":"path","description":"QuickRCM enrollment deficiency identifier in the path. Its parent application must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string","minLength":1,"maxLength":4000,"description":"Required local resolution note, capped at 4000 characters."}},"required":["resolution"]},"example":{"resolution":"example-resolution"}}},"description":"`resolution` is required and capped at 4000 characters. The endpoint looks up the deficiency through an active organization-scoped parent application."},"responses":{"200":{"description":"Deficiency resolved.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"deficiencyId":{"type":"string"},"status":{"type":"string","enum":["RESOLVED"]},"applicationStatusUpdated":{"type":"boolean"}},"required":["deficiencyId","status","applicationStatusUpdated"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"deficiencyId":"00000000-0000-4000-8000-000000000001","status":"RESOLVED","applicationStatusUpdated":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Deficiency not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications/{applicationId}/assignment":{"put":{"operationId":"updatePayerEnrollmentApplicationAssignment","summary":"Assign payer enrollment application","description":"Assigns an active payer enrollment application to a user who is a member of the authenticated organization.\n\n### When to use\nUse this to route enrollment applications to staff queues, enrollment specialists, or supervisors after creating or triaging applications.\n\n### Before calling\nConfirm the application exists in the same tenant and resolve `assignedToId` to a QuickRCM user who is an organization member.\n\n### Request guidance\n`assignedToId` is required. The current public schema does not accept null for unassignment; omit no fields only when no assignment update is intended.\n\n### Request notes\n- `assignedToId` must be a user id with membership in the API key organization.\n- The endpoint is an assignment update, not an invitation or user creation endpoint.\n- No public unassign-null shape is declared.\n\n### Response semantics\nHTTP 200 returns the updated local application summary with `assignedToId` and `meta.organizationId`. The endpoint does not notify the user or create an external task by itself.\n\n### Response notes\n- The response returns the application summary, not user profile details.\n- Related provider summary may be null in this mutation response.\n- The response does not indicate any notification delivery.\n\n### Errors and retries\nTreat 400 as invalid body or assigned user not being an organization member. Treat 404 as missing or wrong-organization application. Re-read assignment after timeouts before retrying.\n\n### Error notes\n- 400 can mean the assigned user is not a member of this organization.\n- 404 means the application is not available in active tenant scope.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"applicationId","in":"path","description":"QuickRCM payer enrollment application identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignedToId":{"type":"string","minLength":1,"description":"Required QuickRCM user id for assignment. The user must be a member of the authenticated organization."}},"required":["assignedToId"]},"example":{"assignedToId":"00000000-0000-4000-8000-000000000001"}}},"description":"`assignedToId` is required. The current public schema does not accept null for unassignment; omit no fields only when no assignment update is intended."},"responses":{"200":{"description":"Payer enrollment application assigned.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"application":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"providerId":{"type":"string"},"provider":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"npi":{"type":"string"}},"required":["id","firstName","lastName","npi"]},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"applicationType":{"type":"string","enum":["INITIAL","REVALIDATION","CHANGE_OF_INFO","ADD_LOCATION","TERMINATION","REINSTATEMENT"]},"applicationMethod":{"type":"string","enum":["CAQH","PAYER_PORTAL","PAPER","EDI","PECOS"]},"payerApplicationId":{"type":["string","null"]},"caqhProviderId":{"type":["string","null"]},"status":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"]},"submissionDate":{"type":["string","null"],"format":"date-time"},"acknowledgmentDate":{"type":["string","null"],"format":"date-time"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"expirationDate":{"type":["string","null"],"format":"date-time"},"nextFollowUpDate":{"type":["string","null"],"format":"date-time"},"followUpCount":{"type":"integer","minimum":0},"estimatedProcessingDays":{"type":["integer","null"]},"assignedToId":{"type":["string","null"]},"formTemplateId":{"type":["string","null"]},"formTemplate":{"type":["object","null"],"properties":{"id":{"type":"string"},"formName":{"type":"string"},"formVersion":{"type":["string","null"]}},"required":["id","formName","formVersion"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","providerId","provider","payerConfigId","payerConfig","applicationType","applicationMethod","payerApplicationId","caqhProviderId","status","submissionDate","acknowledgmentDate","effectiveDate","expirationDate","nextFollowUpDate","followUpCount","estimatedProcessingDays","assignedToId","formTemplateId","formTemplate","createdAt","updatedAt"]}},"required":["application"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"application":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","provider":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","npi":"1234567893"},"payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example payer_enrollment_application_assignment","payerId":"87726"},"applicationType":"INITIAL","applicationMethod":"CAQH","payerApplicationId":"00000000-0000-4000-8000-000000000001","caqhProviderId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","submissionDate":"2026-06-08T10:15:30Z","acknowledgmentDate":"2026-06-08T10:15:30Z","effectiveDate":"2026-06-08T10:15:30Z","expirationDate":"2026-06-08T10:15:30Z","nextFollowUpDate":"2026-06-08T10:15:30Z","followUpCount":1,"estimatedProcessingDays":1,"assignedToId":"00000000-0000-4000-8000-000000000001","formTemplateId":"00000000-0000-4000-8000-000000000001","formTemplate":{"id":"00000000-0000-4000-8000-000000000001","formName":"Example payer_enrollment_application_assignment","formVersion":"example-formversion"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Payer enrollment application not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/provider-profiles":{"post":{"operationId":"createPayerEnrollmentProviderProfile","summary":"Create payer enrollment provider profile","description":"Creates a local provider enrollment profile and initializes local payer enrollment stubs for the organization's configured payers.\n\n### When to use\nUse this before creating payer enrollment applications when the provider does not yet have a Payer Enrollment provider profile in QuickRCM.\n\n### Before calling\nPrepare verified provider identity values. `npi` must be a 10-digit National Provider Identifier (NPI). Optional Council for Affordable Quality Healthcare (CAQH), taxonomy, specialty, license-state, and Medicare identifiers should come from trusted provider or credentialing records.\n\n### Request guidance\n`firstName`, `lastName`, and `npi` are required. `specialties` is capped at 50 entries, and `licenseStates` is capped at 60 two-character entries. The handler rejects a duplicate provider profile for the same organization and National Provider Identifier (NPI).\n\n### Request notes\n- `npi` must match exactly 10 digits.\n- Use synthetic provider names in public examples.\n- Council for Affordable Quality Healthcare (CAQH) and payer identifiers should be treated as sensitive operational identifiers.\n\n### Response semantics\nHTTP 201 returns `data.profile` and `meta.organizationId`. The handler also creates local `PayerEnrollment` rows with NOT_ENROLLED for existing organization payer configurations, using skip-duplicates behavior, but the response does not include a stub count.\n\n### Response notes\n- `data.profile.status` defaults to ACTIVE when profile status is absent.\n- Payer enrollment stubs are a local side effect and are not enumerated in the response.\n- No payer enrollment application is created by this endpoint.\n\n### Errors and retries\nTreat 409 as a profile already existing for the same National Provider Identifier (NPI) in this organization. After a timeout, search/list through internal workflow or attempt application creation with the known provider before retrying profile creation.\n\n### Error notes\n- 409 means a profile already exists for the National Provider Identifier (NPI) in the tenant.\n- 400 can indicate malformed National Provider Identifier (NPI) or invalid array lengths.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100,"description":"Required provider first name. Use synthetic values in public examples."},"lastName":{"type":"string","minLength":1,"maxLength":100,"description":"Required provider last name. Use synthetic values in public examples."},"npi":{"type":"string","pattern":"^\\d{10}$","description":"Required 10-digit provider National Provider Identifier (NPI)."},"taxonomyCode":{"type":"string","minLength":1,"maxLength":50,"description":"Optional provider taxonomy code."},"specialties":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"description":"Optional provider specialty labels, capped at 50 entries."},"licenseStates":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"maxItems":60,"description":"Optional two-character license state entries, capped at 60 entries."},"caqhProviderId":{"type":"string","minLength":1,"maxLength":100,"description":"Optional Council for Affordable Quality Healthcare (CAQH) provider identifier. Treat as sensitive operational data."},"medicareProviderId":{"type":"string","minLength":1,"maxLength":100,"description":"Optional Medicare provider identifier. Treat as sensitive operational data."}},"required":["firstName","lastName","npi"]},"example":{"firstName":"John","lastName":"Smith","npi":"1234567893","taxonomyCode":"example-taxonomycode","specialties":["example-specialties"],"licenseStates":["example-licensestates"],"caqhProviderId":"00000000-0000-4000-8000-000000000001","medicareProviderId":"00000000-0000-4000-8000-000000000001"}}},"description":"`firstName`, `lastName`, and `npi` are required. `specialties` is capped at 50 entries, and `licenseStates` is capped at 60 two-character entries. The handler rejects a duplicate provider profile for the same organization and National Provider Identifier (NPI)."},"responses":{"201":{"description":"Provider enrollment profile created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"profile":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"npi":{"type":"string"},"taxonomyCode":{"type":["string","null"]},"specialties":{"type":"array","items":{"type":"string"}},"licenseStates":{"type":"array","items":{"type":"string"}},"caqhProviderId":{"type":["string","null"]},"medicareProviderId":{"type":["string","null"]},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","firstName","lastName","npi","taxonomyCode","specialties","licenseStates","caqhProviderId","medicareProviderId","status","createdAt","updatedAt"]}},"required":["profile"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"profile":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","npi":"1234567893","taxonomyCode":"example-taxonomycode","specialties":["example-specialties"],"licenseStates":["example-licensestates"],"caqhProviderId":"00000000-0000-4000-8000-000000000001","medicareProviderId":"00000000-0000-4000-8000-000000000001","status":"active","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"409":{"description":"A provider enrollment profile already exists for the NPI.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/provider-profiles/sync-from-credentialing":{"post":{"operationId":"simulateSyncPayerEnrollmentProfileFromCredentialing","summary":"Validate credentialing profile sync","description":"Validates whether an organization-scoped credentialing session has provider information suitable for profile sync, without writing provider enrollment data.\n\n### When to use\nUse this as a safe preflight before implementing or enabling a private workflow that copies provider identity from Credentialing into Payer Enrollment.\n\n### Before calling\nResolve `credentialingSessionId` from Credentialing in the same organization. Ensure the session has provider info and a valid 10-digit National Provider Identifier (NPI). Send `validateOnly: true`.\n\n### Request guidance\n`credentialingSessionId` and `validateOnly: true` are required. The endpoint loads provider info, Council for Affordable Quality Healthcare (CAQH) info, and licenses for validation but does not return those details or create/update a profile.\n\n### Request notes\n- `validateOnly: true` is required.\n- This is a preflight validation endpoint, not a write endpoint.\n- Credentialing provider details are not echoed in the public response.\n\n### Response semantics\nHTTP 202 returns `mode: SIMULATED_ONLY`, the `credentialingSessionId`, `wouldCreateProfile: true`, and `meta.smokeCategory: SIMULATED_ONLY` when validation passes. No provider enrollment data is written.\n\n### Response notes\n- `mode` and `meta.smokeCategory` are SIMULATED_ONLY.\n- `wouldCreateProfile` is a simulation flag, not evidence of a created profile.\n- Use `createPayerEnrollmentProviderProfile` to create a public provider profile directly.\n\n### Errors and retries\nTreat 404 as missing credentialing session or missing provider info in the authenticated organization. Treat 400 as missing or invalid credentialing National Provider Identifier (NPI). Retry transient 5xx and 429 with backoff.\n\n### Error notes\n- 404 can mean credentialing session or provider info is missing.\n- 400 can mean the credentialing session National Provider Identifier (NPI) is missing or not 10 digits.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"credentialingSessionId":{"type":"string","minLength":1,"description":"Required Credentialing session identifier scoped to the API key organization."},"validateOnly":{"type":"boolean","enum":[true],"description":"Required literal true safety flag for public credentialing sync validation."}},"required":["credentialingSessionId","validateOnly"]},"example":{"credentialingSessionId":"00000000-0000-4000-8000-000000000001","validateOnly":true}}},"description":"`credentialingSessionId` and `validateOnly: true` are required. The endpoint loads provider info, Council for Affordable Quality Healthcare (CAQH) info, and licenses for validation but does not return those details or create/update a profile."},"responses":{"202":{"description":"Credentialing sync validation completed without writing provider data.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY"]},"applicationId":{"type":"string"},"submissionMethod":{"type":"string"},"credentialingSessionId":{"type":"string"},"wouldSubmit":{"type":"boolean"},"wouldCreateProfile":{"type":"boolean"},"totalRows":{"type":"integer","minimum":0},"matchedProfiles":{"type":"integer","minimum":0},"matchedPayers":{"type":"integer","minimum":0},"errors":{"type":"array","items":{"type":"string"}}},"required":["mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"smokeCategory":{"type":"string","enum":["SIMULATED_ONLY"]}},"required":["organizationId","smokeCategory"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","applicationId":"00000000-0000-4000-8000-000000000001","submissionMethod":"example-submissionmethod","credentialingSessionId":"00000000-0000-4000-8000-000000000001","wouldSubmit":true,"wouldCreateProfile":true,"totalRows":1,"matchedProfiles":1,"matchedPayers":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","smokeCategory":"SIMULATED_ONLY"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Credentialing session not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/enrollments/{enrollmentId}":{"put":{"operationId":"updatePayerEnrollment","summary":"Update payer enrollment","description":"Updates local payer enrollment fields on one organization-scoped payer enrollment row.\n\n### When to use\nUse this to record local payer-specific enrollment status, payer provider id, group id, effective date, next recredentialing date, or notes after trusted internal review or payer evidence.\n\n### Before calling\nResolve `enrollmentId` from a provider profile's local payer enrollment matrix or a trusted QuickRCM workflow in the same tenant. Prepare only the fields that should change.\n\n### Request guidance\nAll body fields are optional, but an empty object has no useful effect. `enrollmentStatus` must be one of the payer enrollment status enum values. The current schema does not allow null clearing for `payerProviderId`, `payerGroupId`, `effectiveDate`, or `nextRecredentialingDue`; omit means no change.\n\n### Request notes\n- Send only intended changes.\n- Use ISO datetimes for date fields.\n- Do not store raw payer responses in `notes`.\n\n### Response semantics\nHTTP 200 returns `data.enrollment` with local enrollment state and `meta.organizationId`. This endpoint updates QuickRCM local status only; it does not notify claims routing, payer portals, Council for Affordable Quality Healthcare (CAQH), or clearinghouses by itself.\n\n### Response notes\n- The response returns local payer enrollment state.\n- Claims readiness or routing effects are not described by this endpoint response.\n- Nullable response fields can remain null when not recorded.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization enrollment row. After a timeout, re-read the enrollment before retrying to avoid overwriting newer local updates.\n\n### Error notes\n- 404 means the enrollment row is not accessible to the API key organization.\n- 400 can indicate invalid status enum or datetime.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"enrollmentId","in":"path","description":"QuickRCM payer enrollment row identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enrollmentStatus":{"type":"string","enum":["NOT_ENROLLED","APPLICATION_PENDING","ENROLLED_ACTIVE","ENROLLED_RESTRICTED","RECREDENTIALING_DUE","RECREDENTIALING_IN_PROGRESS","SUSPENDED","TERMINATED_ENROLLMENT","DENIED_ENROLLMENT","EXPIRED_ENROLLMENT"],"description":"Optional local payer enrollment status, such as NOT_ENROLLED, APPLICATION_PENDING, ENROLLED_ACTIVE, RECREDENTIALING_DUE, SUSPENDED, or terminal enrollment states."},"payerProviderId":{"type":"string","minLength":1,"maxLength":100,"description":"Optional payer-assigned provider identifier stored locally."},"payerGroupId":{"type":"string","minLength":1,"maxLength":100,"description":"Optional payer-assigned group identifier stored locally."},"effectiveDate":{"type":"string","format":"date-time","description":"Optional ISO datetime for local enrollment effective date."},"nextRecredentialingDue":{"type":"string","format":"date-time","description":"Optional ISO datetime for local recredentialing follow-up."},"notes":{"type":"string","maxLength":4000,"description":"Optional local notes capped at 4000 characters. Avoid raw payer payloads and credentials."}}},"example":{"enrollmentStatus":"NOT_ENROLLED","payerProviderId":"00000000-0000-4000-8000-000000000001","payerGroupId":"00000000-0000-4000-8000-000000000001","effectiveDate":"2026-06-08T10:15:30Z","nextRecredentialingDue":"2026-06-08T10:15:30Z","notes":"Example payer_enrollment note"}}},"description":"All body fields are optional, but an empty object has no useful effect. `enrollmentStatus` must be one of the payer enrollment status enum values. The current schema does not allow null clearing for `payerProviderId`, `payerGroupId`, `effectiveDate`, or `nextRecredentialingDue`; omit means no change."},"responses":{"200":{"description":"Payer enrollment updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"enrollment":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"profileId":{"type":"string"},"payerConfigId":{"type":"string"},"enrollmentStatus":{"type":"string","enum":["NOT_ENROLLED","APPLICATION_PENDING","ENROLLED_ACTIVE","ENROLLED_RESTRICTED","RECREDENTIALING_DUE","RECREDENTIALING_IN_PROGRESS","SUSPENDED","TERMINATED_ENROLLMENT","DENIED_ENROLLMENT","EXPIRED_ENROLLMENT"]},"payerProviderId":{"type":["string","null"]},"payerGroupId":{"type":["string","null"]},"effectiveDate":{"type":["string","null"],"format":"date-time"},"nextRecredentialingDue":{"type":["string","null"],"format":"date-time"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","profileId","payerConfigId","enrollmentStatus","payerProviderId","payerGroupId","effectiveDate","nextRecredentialingDue","notes","createdAt","updatedAt"]}},"required":["enrollment"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"enrollment":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","profileId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","enrollmentStatus":"NOT_ENROLLED","payerProviderId":"00000000-0000-4000-8000-000000000001","payerGroupId":"00000000-0000-4000-8000-000000000001","effectiveDate":"2026-06-08T10:15:30Z","nextRecredentialingDue":"2026-06-08T10:15:30Z","notes":"Example payer_enrollment note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Payer enrollment not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications/bulk-import":{"post":{"operationId":"bulkImportPayerEnrollments","summary":"Validate payer enrollment bulk import","description":"Dry-runs a bulk payer enrollment import by validating provider NPIs and payer names against organization-scoped QuickRCM records.\n\n### When to use\nUse this to validate a spreadsheet or integration feed before requesting a private or future bulk write workflow.\n\n### Before calling\nCreate provider profiles and payer configurations for the organization first. Prepare 1 to 100 enrollment rows with 10-digit National Provider Identifier (NPI), provider names, payer name, and enrollment status. Send `dryRun: true`.\n\n### Request guidance\n`dryRun` must be true. The current dry-run handler validates every row against the public schema, including names, status enum, optional dates, and optional payer provider id. After schema validation, it matches only unique `enrollments[].npi` values against provider profiles and unique `enrollments[].payerName` values against payer configurations in the authenticated organization. `idempotencyKey` is accepted by the schema but is not used for dedupe or replay because no rows are written.\n\n### Request notes\n- `dryRun: true` is required.\n- `enrollments` must contain 1 to 100 rows.\n- The API matches providers by unique `npi` and payers by exact `payerName`; `firstName`, `lastName`, `enrollmentStatus`, dates, and payer provider id are schema-validated but not used for row lookup.\n- The endpoint is simulated-only and does not use `idempotencyKey` for dedupe.\n\n### Response semantics\nHTTP 202 returns `mode: SIMULATED_ONLY`, `totalRows`, `matchedProfiles`, `matchedPayers`, and an `errors` array. It does not create or update provider profiles, payer configurations, applications, or enrollment rows. A 202 response can still include row-indexed lookup errors such as provider profile not found or payer not found.\n\n### Response notes\n- `errors` contains row-indexed validation findings for missing providers or payers.\n- `matchedProfiles` and `matchedPayers` count unique matched NPIs and payer names, not successful row count.\n- No rows are written by this public endpoint.\n\n### Errors and retries\nFix schema-level 400s and row-level 202 errors before attempting any write workflow. Treat 400 as malformed body, missing `dryRun: true`, invalid National Provider Identifier (NPI), invalid status, invalid datetime, missing required row fields, or too many rows. Retry 429 with backoff.\n\n### Error notes\n- 400 covers schema-level validation; row-level lookup misses are returned inside the 202 response.\n- Do not rely on `idempotencyKey` for dedupe because no write occurs.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","enum":[true],"description":"Required literal true safety flag. The public bulk import endpoint is validation-only."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":128,"description":"Optional caller retry marker capped at 128 characters. Current dry-run behavior does not use it for dedupe, replay, or row matching."},"enrollments":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"string","pattern":"^\\d{10}$","description":"Required 10-digit provider National Provider Identifier (NPI). The dry-run handler matches unique NPI values against provider profiles in the authenticated organization."},"firstName":{"type":"string","minLength":1,"maxLength":100,"description":"Required provider first name capped at 100 characters. It is schema-validated but not used for current dry-run matching; examples must use synthetic names."},"lastName":{"type":"string","minLength":1,"maxLength":100,"description":"Required provider last name capped at 100 characters. It is schema-validated but not used for current dry-run matching; examples must use synthetic names."},"payerName":{"type":"string","minLength":1,"maxLength":200,"description":"Required payer configuration name capped at 200 characters. The dry-run handler matches unique payer names against payer configurations in the authenticated organization."},"enrollmentStatus":{"type":"string","enum":["NOT_ENROLLED","APPLICATION_PENDING","ENROLLED_ACTIVE","ENROLLED_RESTRICTED","RECREDENTIALING_DUE","RECREDENTIALING_IN_PROGRESS","SUSPENDED","TERMINATED_ENROLLMENT","DENIED_ENROLLMENT","EXPIRED_ENROLLMENT"],"description":"Required local payer enrollment status enum value for the proposed row. It is schema-validated but no enrollment row is written."},"effectiveDate":{"type":"string","format":"date-time","description":"Optional ISO datetime for the proposed enrollment effective date. It is schema-validated only in the current dry-run handler."},"payerProviderId":{"type":"string","minLength":1,"maxLength":100,"description":"Optional payer-assigned provider identifier capped at 100 characters. It is schema-validated only and is not written by this dry-run endpoint."},"nextRecredentialingDue":{"type":"string","format":"date-time","description":"Optional ISO datetime for the proposed next recredentialing due date. It is schema-validated only in the current dry-run handler."}},"required":["npi","firstName","lastName","payerName","enrollmentStatus"]},"minItems":1,"maxItems":100,"description":"Array of 1 to 100 enrollment rows to validate. Rows are schema-validated first, then only unique National Provider Identifier (NPI) and payer-name values are used for organization-scoped lookups."}},"required":["dryRun","enrollments"]},"example":{"dryRun":true,"enrollments":[{"npi":"1234567893","firstName":"John","lastName":"Smith","payerName":"Example import_payer_enrollment","enrollmentStatus":"NOT_ENROLLED","effectiveDate":"2026-06-08T10:15:30Z","payerProviderId":"00000000-0000-4000-8000-000000000001","nextRecredentialingDue":"2026-06-08T10:15:30Z"}],"idempotencyKey":"example-idempotencykey"}}},"description":"`dryRun` must be true. The current dry-run handler validates every row against the public schema, including names, status enum, optional dates, and optional payer provider id. After schema validation, it matches only unique `enrollments[].npi` values against provider profiles and unique `enrollments[].payerName` values against payer configurations in the authenticated organization. `idempotencyKey` is accepted by the schema but is not used for dedupe or replay because no rows are written."},"responses":{"202":{"description":"Bulk import validation completed without writing rows.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["SIMULATED_ONLY"]},"applicationId":{"type":"string"},"submissionMethod":{"type":"string"},"credentialingSessionId":{"type":"string"},"wouldSubmit":{"type":"boolean"},"wouldCreateProfile":{"type":"boolean"},"totalRows":{"type":"integer","minimum":0},"matchedProfiles":{"type":"integer","minimum":0},"matchedPayers":{"type":"integer","minimum":0},"errors":{"type":"array","items":{"type":"string"}}},"required":["mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"smokeCategory":{"type":"string","enum":["SIMULATED_ONLY"]}},"required":["organizationId","smokeCategory"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"mode":"SIMULATED_ONLY","applicationId":"00000000-0000-4000-8000-000000000001","submissionMethod":"example-submissionmethod","credentialingSessionId":"00000000-0000-4000-8000-000000000001","wouldSubmit":true,"wouldCreateProfile":true,"totalRows":1,"matchedProfiles":1,"matchedPayers":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","smokeCategory":"SIMULATED_ONLY"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications/status/bulk":{"put":{"operationId":"bulkUpdatePayerEnrollmentApplicationStatus","summary":"Bulk update payer enrollment application status","description":"Attempts to apply one local status transition to up to 100 active payer enrollment applications in the authenticated organization.\n\n### When to use\nUse this for batch workflow movement after staff review or validated operational evidence, such as moving several applications from READY_FOR_REVIEW to SUBMITTED in local state.\n\n### Before calling\nCollect application ids from the same organization and confirm each current status can transition to `newStatus`. Prepare an optional note that applies to all successful updates.\n\n### Request guidance\n`applicationIds` must contain 1 to 100 ids. `newStatus` is required and must be reachable from each application's current status using the same transition graph as the single status endpoint: DRAFT -> AUTO_FILLING, READY_FOR_REVIEW, PENDING_DOCUMENTS, WITHDRAWN; AUTO_FILLING -> READY_FOR_REVIEW, DRAFT; READY_FOR_REVIEW -> SUBMITTED, PENDING_DOCUMENTS, DRAFT, WITHDRAWN; PENDING_DOCUMENTS -> READY_FOR_REVIEW, SUBMITTED, WITHDRAWN; SUBMITTED -> ACKNOWLEDGED, IN_REVIEW, DEFICIENCY_RECEIVED, APPROVED, DENIED, WITHDRAWN; ACKNOWLEDGED -> IN_REVIEW, DEFICIENCY_RECEIVED, APPROVED, DENIED; IN_REVIEW -> DEFICIENCY_RECEIVED, APPROVED, DENIED; DEFICIENCY_RECEIVED -> DEFICIENCY_RESOLVED, DENIED, WITHDRAWN; DEFICIENCY_RESOLVED -> IN_REVIEW, APPROVED, DENIED; APPROVED -> EFFECTIVE, WITHDRAWN; EFFECTIVE -> EXPIRED, TERMINATED; EXPIRED -> DRAFT; TERMINATED -> DRAFT. DENIED and WITHDRAWN have no outbound transitions. The handler processes found applications individually and returns per-id errors for missing/inaccessible records and invalid transitions.\n\n### Request notes\n- All ids must be from the API key organization.\n- Transition validity is checked per application.\n- Use a note that is appropriate for every updated application.\n\n### Response semantics\nHTTP 200 returns `updated`, `skipped`, and `errors`. `updated` counts successful local status/statusHistory updates. `skipped` counts found applications skipped because their transition was invalid. Missing or inaccessible ids appear in `errors` but are not counted in `skipped` by current handler behavior. Unlike the single status endpoint, current bulk APPROVED updates do not stamp `effectiveDate`.\n\n### Response notes\n- HTTP 200 can include an `errors` array.\n- `skipped` does not include missing or inaccessible ids in current behavior.\n- Successful bulk updates change only local `status` and `statusHistory`.\n- No external payer action is triggered, and bulk APPROVED updates do not set `effectiveDate` in the current handler.\n\n### Errors and retries\nTreat 200 with non-empty `errors` as partial success requiring caller reconciliation. Treat 400 as malformed ids, empty array, too many ids, or invalid `newStatus`. After timeouts, re-read affected applications before retrying.\n\n### Error notes\n- 400 means schema validation failed before per-application processing.\n- Per-id invalid transitions are reported in `data.errors`.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"applicationIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Array of 1 to 100 payer enrollment application ids to update within the authenticated organization."},"newStatus":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"],"description":"Required target local application status applied to each eligible application when that application's current status can transition to it."},"note":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional bulk status-history note capped at 1000 characters. The same note is attached to every successful local status update; avoid Protected Health Information (PHI) and raw payer payloads."}},"required":["applicationIds","newStatus"]},"example":{"applicationIds":["example-applicationids"],"newStatus":"DRAFT","note":"Example update_payer_enrollment_application_statu note"}}},"description":"`applicationIds` must contain 1 to 100 ids. `newStatus` is required and must be reachable from each application's current status using the same transition graph as the single status endpoint: DRAFT -> AUTO_FILLING, READY_FOR_REVIEW, PENDING_DOCUMENTS, WITHDRAWN; AUTO_FILLING -> READY_FOR_REVIEW, DRAFT; READY_FOR_REVIEW -> SUBMITTED, PENDING_DOCUMENTS, DRAFT, WITHDRAWN; PENDING_DOCUMENTS -> READY_FOR_REVIEW, SUBMITTED, WITHDRAWN; SUBMITTED -> ACKNOWLEDGED, IN_REVIEW, DEFICIENCY_RECEIVED, APPROVED, DENIED, WITHDRAWN; ACKNOWLEDGED -> IN_REVIEW, DEFICIENCY_RECEIVED, APPROVED, DENIED; IN_REVIEW -> DEFICIENCY_RECEIVED, APPROVED, DENIED; DEFICIENCY_RECEIVED -> DEFICIENCY_RESOLVED, DENIED, WITHDRAWN; DEFICIENCY_RESOLVED -> IN_REVIEW, APPROVED, DENIED; APPROVED -> EFFECTIVE, WITHDRAWN; EFFECTIVE -> EXPIRED, TERMINATED; EXPIRED -> DRAFT; TERMINATED -> DRAFT. DENIED and WITHDRAWN have no outbound transitions. The handler processes found applications individually and returns per-id errors for missing/inaccessible records and invalid transitions."},"responses":{"200":{"description":"Bulk status update completed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"updated":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"errors":{"type":"array","items":{"type":"object","properties":{"applicationId":{"type":"string"},"reason":{"type":"string"}},"required":["applicationId","reason"]}}},"required":["updated","skipped","errors"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"updated":1,"skipped":1,"errors":[{"applicationId":"00000000-0000-4000-8000-000000000001","reason":"example-reason"}]},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payer-enrollment/applications/{applicationId}/clone":{"post":{"operationId":"clonePayerEnrollmentApplication","summary":"Clone payer enrollment application","description":"Creates a local DRAFT application for a different organization-scoped target payer by copying selected data from a source application.\n\n### When to use\nUse this when a provider needs a similar enrollment application for another payer configuration and source application data should seed the new local draft.\n\n### Before calling\nLoad the source application and choose a `targetPayerConfigId` from the same organization. Check whether an active application already exists for the source provider, target payer, and source application type.\n\n### Request guidance\n`targetPayerConfigId` is required. The handler copies provider id, credentialing session id, application type, application method, and application data from the source, selects an active form template by target payer name when available, and initializes status DRAFT.\n\n### Request notes\n- The target payer must be an organization-scoped payer configuration.\n- Duplicate detection uses provider, target payer, source application type, active status, and organization.\n- Cloned data remains local draft data.\n\n### Response semantics\nHTTP 201 returns the cloned local application and `meta.organizationId`. The clone is a draft only; it does not submit, notify, or synchronize with the target payer.\n\n### Response notes\n- Status is DRAFT on clone.\n- The response may omit or null related provider summary if not reloaded.\n- No external submission or payer notification occurs.\n\n### Errors and retries\nTreat 404 as missing source application or target payer configuration in the authenticated organization. Treat 409 as an active duplicate for the provider, target payer, and application type. After timeouts, list applications for the provider and target payer before retrying.\n\n### Error notes\n- 404 can mean source application or target payer configuration is not accessible.\n- 409 means an active duplicate already exists.\n","tags":["Payer Enrollment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"applicationId","in":"path","description":"QuickRCM payer enrollment application identifier. It must belong to the organization selected by the bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"targetPayerConfigId":{"type":"string","minLength":1,"description":"Required organization-scoped payer configuration id for the cloned draft."}},"required":["targetPayerConfigId"]},"example":{"targetPayerConfigId":"00000000-0000-4000-8000-000000000001"}}},"description":"`targetPayerConfigId` is required. The handler copies provider id, credentialing session id, application type, application method, and application data from the source, selects an active form template by target payer name when available, and initializes status DRAFT."},"responses":{"201":{"description":"Payer enrollment application cloned.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"application":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"providerId":{"type":"string"},"provider":{"type":["object","null"],"properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"npi":{"type":"string"}},"required":["id","firstName","lastName","npi"]},"payerConfigId":{"type":"string"},"payerConfig":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"},"payerId":{"type":["string","null"]}},"required":["id","payerName","payerId"]},"applicationType":{"type":"string","enum":["INITIAL","REVALIDATION","CHANGE_OF_INFO","ADD_LOCATION","TERMINATION","REINSTATEMENT"]},"applicationMethod":{"type":"string","enum":["CAQH","PAYER_PORTAL","PAPER","EDI","PECOS"]},"payerApplicationId":{"type":["string","null"]},"caqhProviderId":{"type":["string","null"]},"status":{"type":"string","enum":["DRAFT","AUTO_FILLING","READY_FOR_REVIEW","PENDING_DOCUMENTS","SUBMITTED","ACKNOWLEDGED","IN_REVIEW","DEFICIENCY_RECEIVED","DEFICIENCY_RESOLVED","APPROVED","EFFECTIVE","DENIED","WITHDRAWN","EXPIRED","TERMINATED"]},"submissionDate":{"type":["string","null"],"format":"date-time"},"acknowledgmentDate":{"type":["string","null"],"format":"date-time"},"effectiveDate":{"type":["string","null"],"format":"date-time"},"expirationDate":{"type":["string","null"],"format":"date-time"},"nextFollowUpDate":{"type":["string","null"],"format":"date-time"},"followUpCount":{"type":"integer","minimum":0},"estimatedProcessingDays":{"type":["integer","null"]},"assignedToId":{"type":["string","null"]},"formTemplateId":{"type":["string","null"]},"formTemplate":{"type":["object","null"],"properties":{"id":{"type":"string"},"formName":{"type":"string"},"formVersion":{"type":["string","null"]}},"required":["id","formName","formVersion"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","providerId","provider","payerConfigId","payerConfig","applicationType","applicationMethod","payerApplicationId","caqhProviderId","status","submissionDate","acknowledgmentDate","effectiveDate","expirationDate","nextFollowUpDate","followUpCount","estimatedProcessingDays","assignedToId","formTemplateId","formTemplate","createdAt","updatedAt"]}},"required":["application"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"application":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","providerId":"00000000-0000-4000-8000-000000000001","provider":{"id":"00000000-0000-4000-8000-000000000001","firstName":"John","lastName":"Smith","npi":"1234567893"},"payerConfigId":"00000000-0000-4000-8000-000000000001","payerConfig":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example clone_payer_enrollment_application","payerId":"87726"},"applicationType":"INITIAL","applicationMethod":"CAQH","payerApplicationId":"00000000-0000-4000-8000-000000000001","caqhProviderId":"00000000-0000-4000-8000-000000000001","status":"DRAFT","submissionDate":"2026-06-08T10:15:30Z","acknowledgmentDate":"2026-06-08T10:15:30Z","effectiveDate":"2026-06-08T10:15:30Z","expirationDate":"2026-06-08T10:15:30Z","nextFollowUpDate":"2026-06-08T10:15:30Z","followUpCount":1,"estimatedProcessingDays":1,"assignedToId":"00000000-0000-4000-8000-000000000001","formTemplateId":"00000000-0000-4000-8000-000000000001","formTemplate":{"id":"00000000-0000-4000-8000-000000000001","formName":"Example clone_payer_enrollment_application","formVersion":"example-formversion"},"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Source application or target payer not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"An active application already exists for the provider and target payer.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/remittances":{"get":{"operationId":"listPaymentPostingRemittances","summary":"List payment posting remittances","description":"Returns a paginated list of sanitized remittance summaries owned by the organization selected by the bearer API key, with optional filters for local remittance status, payer name, and inclusive check-date bounds.\n\n### When to use\nUse this endpoint for ERA queues, remittance worklists, reconciliation selectors, or integration polling before opening a specific payment record or running local matching and staging workflows.\n\n### Before calling\nAuthenticate with an API key that has `payment-posting:read` or `payment-posting:write`. Choose bounded pagination and status/date filters that match the work queue. Do not send `organizationId` as a public tenant selector.\n\n### Request guidance\n`skip` defaults to 0 and is capped at 10000. `take` defaults to 50 and is capped at 100. `status` must be one of the public remittance workflow statuses. `payerName` is a case-insensitive contains filter. `startDate` and `endDate` are inclusive remittance check-date filters. Date-only values are parsed as the bound timestamp itself; `endDate` is not expanded to the end of that calendar day, so callers that need whole-day coverage should send an explicit final timestamp.\n\n### Response semantics\nHTTP 200 returns `data.remittances`, `total`, `skip`, `take`, and `meta.organizationId`. Each summary includes check metadata, payment method, total amount, payer name/id, local workflow status, local match summary fields, and aggregate counts. It omits raw X12 835 content, patient demographics, payer payloads, and storage details.\n\n### Errors and retries\nTreat 400 as invalid pagination, enum, or date input; 401/403 as credential, scope, or tenant-context failures; and 429 as a backoff signal. Retry transient 5xx responses with bounded retries and stable filters.\n\n### Error notes\n- Treat 400 as invalid pagination, enum, or date input; 401/403 as credential, scope, or tenant-context failures; and 429 as a backoff signal. Retry transient 5xx responses with bounded retries and stable filters.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"skip","in":"query","description":"Zero-based number of remittance rows to skip. Defaults to 0 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"take","in":"query","description":"Maximum remittance rows to return. Defaults to 50 and cannot exceed 100."},{"schema":{"type":"string","enum":["PROCESSING","RECEIVED","MATCHED","PARTIALLY_MATCHED","UNMATCHED","REQUIRES_REVIEW","POSTED","PARTIALLY_POSTED","CLOSED"]},"required":false,"name":"status","in":"query","description":"Optional local remittance workflow status: PROCESSING, RECEIVED, MATCHED, PARTIALLY_MATCHED, UNMATCHED, REQUIRES_REVIEW, POSTED, PARTIALLY_POSTED, or CLOSED."},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"payerName","in":"query","description":"Optional case-insensitive contains filter over the local remittance payer name."},{"schema":{"type":"string","minLength":1,"description":"Inclusive check-date lower bound. ISO date or datetime accepted."},"required":false,"description":"Inclusive lower timestamp bound for remittance check date. Send a consistent ISO date or datetime string; date-only input is parsed as the timestamp represented by that date.","name":"startDate","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Inclusive check-date upper bound. ISO date or datetime accepted."},"required":false,"description":"Inclusive upper timestamp bound for remittance check date. Date-only input is not expanded to 23:59:59; send the exact final timestamp that should be included.","name":"endDate","in":"query"}],"responses":{"200":{"description":"Remittances for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"remittances":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"checkNumber":{"type":"string"},"checkDate":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"},"totalAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"payerName":{"type":"string"},"payerId":{"type":"string"},"status":{"type":"string","enum":["PROCESSING","RECEIVED","MATCHED","PARTIALLY_MATCHED","UNMATCHED","REQUIRES_REVIEW","POSTED","PARTIALLY_POSTED","CLOSED"]},"matchRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"overallConfidence":{"type":["string","null"],"enum":["HIGH","MEDIUM","LOW","NONE"]},"paymentCount":{"type":"integer","minimum":0},"remittanceClaimCount":{"type":"integer","minimum":0},"postedClaimCount":{"type":"integer","minimum":0},"unmatchedClaimCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","checkNumber","checkDate","paymentMethod","totalAmount","payerName","payerId","status","matchRate","overallConfidence","paymentCount","remittanceClaimCount","postedClaimCount","unmatchedClaimCount","createdAt"],"description":"Payment posting remittance summary. Raw 835 payloads and patient demographics are omitted."}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["remittances","total","skip","take"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"remittances":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","checkNumber":"example-checknumber","checkDate":"2026-06-08T10:15:30Z","paymentMethod":"example-paymentmethod","totalAmount":"example-totalamount","payerName":"Example payment_posting_remittance","payerId":"87726","status":"PROCESSING","matchRate":"example-matchrate","overallConfidence":"HIGH","paymentCount":1,"remittanceClaimCount":1,"postedClaimCount":1,"unmatchedClaimCount":1,"createdAt":"2026-06-08T10:15:30Z"}],"total":1,"skip":1,"take":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/payments/{paymentId}":{"get":{"operationId":"getPaymentPostingPayment","summary":"Get posted payment","description":"Returns one payment posting record when it is linked through a remittance in the authenticated organization, including sanitized remittance, remittance-claim, claim-control, line-payment, and adjustment summaries.\n\n### When to use\nUse this after a remittance list, payment worklist, reconciliation process, or local workflow gives you a `paymentId` for the same tenant.\n\n### Before calling\nUse a `paymentId` obtained from QuickRCM in the same API-key organization. Read access accepts `payment-posting:read` or `payment-posting:write`.\n\n### Request guidance\nPass `paymentId` in the path. The endpoint has no request body and no public tenant selector. Do not include raw payer responses, EDI, signed storage URLs, payer credentials, or patient demographic context.\n\n### Response semantics\nHTTP 200 returns `data.payment` and `meta.organizationId`. The payment record may have `status: STAGED` or `status: POSTED`; do not document this endpoint as posted-only. The handler scopes access through `payment.remittance.organizationId` and returns local financial strings, claim-control summaries, match metadata, nested remittance/remittance-claim summaries, payment lines, and adjustments. It omits patient demographics, raw X12 835 payloads, payer payloads, and storage details.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization payment context unless a prior trusted response proves the payment should exist. Retry only transient 5xx or 429 responses with backoff.\n\n### Error notes\n- Treat 404 as missing or wrong-organization payment context unless a prior trusted response proves the payment should exist. Retry only transient 5xx or 429 responses with backoff.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"paymentId","in":"path","description":"QuickRCM payment identifier in the path. The payment must be linked to a remittance in the API key organization."}],"responses":{"200":{"description":"Posted payment detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"payment":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"remittanceId":{"type":"string"},"remittanceClaimId":{"type":"string"},"claimId":{"type":"string"},"claimControlNumber":{"type":["string","null"]},"claimType":{"type":["string","null"]},"claimStatus":{"type":["string","null"]},"claimStatusCode":{"type":"string"},"claimChargeAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"paymentAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"patientResponsibility":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"matchConfidence":{"type":["string","null"],"enum":["HIGH","MEDIUM","LOW","NONE"]},"matchMethod":{"type":["string","null"]},"status":{"type":"string","enum":["STAGED","POSTED"]},"remittance":{"type":"object","properties":{"id":{"type":"string"},"checkNumber":{"type":"string"},"checkDate":{"type":"string","format":"date-time"},"payerName":{"type":"string"},"payerId":{"type":"string"},"paymentMethod":{"type":"string"},"totalAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"status":{"type":"string","enum":["PROCESSING","RECEIVED","MATCHED","PARTIALLY_MATCHED","UNMATCHED","REQUIRES_REVIEW","POSTED","PARTIALLY_POSTED","CLOSED"]}},"required":["id","checkNumber","checkDate","payerName","payerId","paymentMethod","totalAmount","status"]},"remittanceClaim":{"type":"object","properties":{"id":{"type":"string"},"eraClaimControlNumber":{"type":"string"},"payerClaimControlNumber":{"type":["string","null"]},"claimStatusCode":{"type":"string"},"status":{"type":"string","enum":["UNMATCHED","MATCHED","POSTED","FAILED"]},"paymentAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"patientResponsibility":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["id","eraClaimControlNumber","payerClaimControlNumber","claimStatusCode","status","paymentAmount","patientResponsibility"]},"paymentLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"claimLineId":{"type":["string","null"]},"procedureCode":{"type":"string"},"billedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"paidAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"allowedAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"groupCode":{"type":"string"},"reasonCode":{"type":"string"},"amount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["id","groupCode","reasonCode","amount"]}}},"required":["id","claimLineId","procedureCode","billedAmount","paidAmount","allowedAmount","adjustments"]}},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"groupCode":{"type":"string"},"reasonCode":{"type":"string"},"amount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["id","groupCode","reasonCode","amount"]}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","remittanceId","remittanceClaimId","claimId","claimControlNumber","claimType","claimStatus","claimStatusCode","claimChargeAmount","paymentAmount","patientResponsibility","matchConfidence","matchMethod","status","remittance","remittanceClaim","paymentLines","adjustments","createdAt"],"description":"Posted payment detail. Patient demographics, raw 835 payloads, and payer payloads are omitted."}},"required":["payment"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"payment":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","remittanceId":"00000000-0000-4000-8000-000000000001","remittanceClaimId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","claimControlNumber":"example-claimcontrolnumber","claimType":"example-claimtype","claimStatus":"example-claimstatus","claimStatusCode":"example-claimstatuscode","claimChargeAmount":"example-claimchargeamount","paymentAmount":"example-paymentamount","patientResponsibility":"example-patientresponsibility","matchConfidence":"HIGH","matchMethod":"example-matchmethod","status":"STAGED","remittance":{"id":"00000000-0000-4000-8000-000000000001","checkNumber":"example-checknumber","checkDate":"2026-06-08T10:15:30Z","payerName":"Example payment_posting_payment","payerId":"87726","paymentMethod":"example-paymentmethod","totalAmount":"example-totalamount","status":"PROCESSING"},"remittanceClaim":{"id":"00000000-0000-4000-8000-000000000001","eraClaimControlNumber":"example-eraclaimcontrolnumber","payerClaimControlNumber":"example-payerclaimcontrolnumber","claimStatusCode":"example-claimstatuscode","status":"UNMATCHED","paymentAmount":"example-paymentamount","patientResponsibility":"example-patientresponsibility"},"paymentLines":[{"id":"00000000-0000-4000-8000-000000000001","claimLineId":"00000000-0000-4000-8000-000000000001","procedureCode":"example-procedurecode","billedAmount":"example-billedamount","paidAmount":"example-paidamount","allowedAmount":"example-allowedamount","adjustments":[{"id":"00000000-0000-4000-8000-000000000001","groupCode":"example-groupcode","reasonCode":"example-reasoncode","amount":"example-amount"}]}],"adjustments":[{"id":"00000000-0000-4000-8000-000000000001","groupCode":"example-groupcode","reasonCode":"example-reasoncode","amount":"example-amount"}],"createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/remittances/import":{"post":{"operationId":"importPaymentPostingRemittance","summary":"Validate or queue ERA remittance import","description":"Validates ERA import metadata for the authenticated organization and checks for a duplicate remittance by exact organization, check number, parsed check date, and payer name. The public wrapper does not download files, parse raw X12 835 EDI, or create remittance rows.\n\n### When to use\nUse this endpoint before an external integration asks QuickRCM to accept ERA import metadata, especially to detect duplicate check metadata without exposing raw remittance content through the public API.\n\n### Before calling\nAuthenticate with `payment-posting:write`. Prepare metadata from a trusted storage workflow. Use `validateOnly: true` for validation, or `queueOnly: true` for queue simulation. Do not send both safe-mode flags as false.\n\n### Request guidance\nEither `s3Key` or `s3Url` is required by the schema, but examples must use synthetic placeholders only. `checkNumber`, `checkDate`, and `payerName` are required. `checkDate` must be a date-time string. `validateOnly` defaults to true and takes precedence in the response mode. When both `validateOnly` and `queueOnly` are false, the handler returns 400.\n\n### Response semantics\nHTTP 202 returns action `IMPORT_ERA`, mode `VALIDATE_ONLY` or `QUEUE_ONLY`, `externalRisk: SIMULATED_ONLY`, `queued: false`, and duplicate metadata. `accepted` is false when a duplicate remittance exists. This is not evidence that an ERA file was downloaded, parsed, persisted, queued, or posted.\n\n### Errors and retries\nFix 400 validation failures, missing storage pointer placeholders, invalid `checkDate`, or unsafe flag combinations before retrying. Treat duplicate responses as business outcomes rather than transient failures. Retry 429 and transient 5xx responses with backoff.\n\n### Error notes\n- Fix 400 validation failures, missing storage pointer placeholders, invalid `checkDate`, or unsafe flag combinations before retrying. Treat duplicate responses as business outcomes rather than transient failures. Retry 429 and transient 5xx responses with backoff.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"s3Key":{"type":"string","minLength":1,"maxLength":1024,"description":"Optional organization-scoped storage object key accepted by the schema. Public docs should use non-resolving placeholders only and must not expose real keys."},"s3Url":{"type":"string","minLength":1,"maxLength":2048,"description":"Optional ERA object URL accepted by the schema. Public docs should use placeholders only and must not expose signed or real storage URLs."},"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Optional display filename for operator context; do not include patient names or secrets."},"checkNumber":{"type":"string","minLength":1,"maxLength":120,"description":"Required remittance check or EFT trace identifier used for duplicate detection with check date, payer name, and authenticated organization."},"checkDate":{"type":"string","format":"date-time","description":"Required remittance check date as an ISO date-time string. The handler parses this value before duplicate lookup."},"payerName":{"type":"string","minLength":1,"maxLength":200,"description":"Required local payer display name used in exact duplicate lookup with check number and check date."},"validateOnly":{"type":["boolean","null"],"default":true,"description":"Safe-mode flag that defaults to true. When true, response mode is VALIDATE_ONLY and no live import side effects occur."},"queueOnly":{"type":["boolean","null"],"default":false,"description":"Safe-mode flag for queue simulation. Current public handler still returns `queued: false`."}},"required":["checkNumber","checkDate","payerName"]},"example":{"checkNumber":"example-checknumber","checkDate":"2026-06-08T10:15:30Z","payerName":"Example import_payment_posting_remittance","s3Key":"example-s3key","s3Url":"https://example.quickintell.com/resource","fileName":"Example import_payment_posting_remittance","validateOnly":true,"queueOnly":false}}},"description":"Either `s3Key` or `s3Url` is required by the schema, but examples must use synthetic placeholders only. `checkNumber`, `checkDate`, and `payerName` are required. `checkDate` must be a date-time string. `validateOnly` defaults to true and takes precedence in the response mode. When both `validateOnly` and `queueOnly` are false, the handler returns 400."},"responses":{"202":{"description":"ERA import request validated or accepted for safe queue simulation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"action":{"type":"string"},"mode":{"type":"string"},"externalRisk":{"type":"string"}},"required":["action","mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"action":"example-action","mode":"example-mode","externalRisk":"example-externalrisk"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/remittances/{remittanceId}":{"put":{"operationId":"updatePaymentPostingRemittance","summary":"Update remittance metadata","description":"Updates non-PHI metadata on one organization-owned remittance and returns the refreshed sanitized remittance summary.\n\n### When to use\nUse this endpoint to correct local check metadata, payment method, payer display metadata, payer ID, or total amount after a remittance exists in QuickRCM.\n\n### Before calling\nAuthenticate with `payment-posting:write` and use a `remittanceId` from the same organization. Include at least one updatable field in the JSON body.\n\n### Request guidance\nThe route accepts partial metadata fields: `checkNumber`, `checkDate`, `paymentMethod`, `totalAmount`, `payerName`, and `payerId`. `checkDate` must parse as a date-time and `totalAmount` must be non-negative. Do not include raw ERA content, payer payloads, patient data, or storage pointers.\n\n### Response semantics\nHTTP 200 returns `data.remittance`, a sanitized remittance summary with aggregate counts. This is a local metadata update and does not re-parse ERA files, rerun matching, or post payments.\n\n### Errors and retries\nA 400 can mean an empty body, invalid date, or invalid field value. A 404 means the remittance does not belong to the authenticated organization or does not exist. After a timeout, re-read the remittance before retrying to avoid overwriting fresher edits.\n\n### Error notes\n- A 400 can mean an empty body, invalid date, or invalid field value. A 404 means the remittance does not belong to the authenticated organization or does not exist. After a timeout, re-read the remittance before retrying to avoid overwriting fresher edits.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"remittanceId","in":"path","description":"QuickRCM remittance identifier in the path. It must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"checkNumber":{"type":"string","minLength":1,"maxLength":120,"description":"Optional replacement local remittance check or EFT trace identifier."},"checkDate":{"type":"string","format":"date-time","description":"Optional replacement remittance check date as an ISO date-time string."},"paymentMethod":{"type":"string","minLength":1,"maxLength":80,"description":"Optional local payment method label, capped at 80 characters."},"totalAmount":{"type":["number","null"],"minimum":0,"description":"Optional non-negative remittance total amount supplied as a JSON number in the request and returned as a string in responses."},"payerName":{"type":"string","minLength":1,"maxLength":200,"description":"Optional local payer display name for the remittance."},"payerId":{"type":"string","minLength":1,"maxLength":120,"description":"Optional payer identifier stored on the local remittance."}}},"example":{"checkNumber":"example-checknumber","checkDate":"2026-06-08T10:15:30Z","paymentMethod":"example-paymentmethod","totalAmount":1,"payerName":"Example payment_posting_remittance","payerId":"87726"}}},"description":"The route accepts partial metadata fields: `checkNumber`, `checkDate`, `paymentMethod`, `totalAmount`, `payerName`, and `payerId`. `checkDate` must parse as a date-time and `totalAmount` must be non-negative. Do not include raw ERA content, payer payloads, patient data, or storage pointers."},"responses":{"200":{"description":"Updated remittance summary.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"remittance":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"checkNumber":{"type":"string"},"checkDate":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"},"totalAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"payerName":{"type":"string"},"payerId":{"type":"string"},"status":{"type":"string","enum":["PROCESSING","RECEIVED","MATCHED","PARTIALLY_MATCHED","UNMATCHED","REQUIRES_REVIEW","POSTED","PARTIALLY_POSTED","CLOSED"]},"matchRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"overallConfidence":{"type":["string","null"],"enum":["HIGH","MEDIUM","LOW","NONE"]},"paymentCount":{"type":"integer","minimum":0},"remittanceClaimCount":{"type":"integer","minimum":0},"postedClaimCount":{"type":"integer","minimum":0},"unmatchedClaimCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","checkNumber","checkDate","paymentMethod","totalAmount","payerName","payerId","status","matchRate","overallConfidence","paymentCount","remittanceClaimCount","postedClaimCount","unmatchedClaimCount","createdAt"],"description":"Payment posting remittance summary. Raw 835 payloads and patient demographics are omitted."}},"required":["remittance"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"remittance":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","checkNumber":"example-checknumber","checkDate":"2026-06-08T10:15:30Z","paymentMethod":"example-paymentmethod","totalAmount":"example-totalamount","payerName":"Example payment_posting_remittance","payerId":"87726","status":"PROCESSING","matchRate":"example-matchrate","overallConfidence":"HIGH","paymentCount":1,"remittanceClaimCount":1,"postedClaimCount":1,"unmatchedClaimCount":1,"createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/remittances/{remittanceId}/match":{"post":{"operationId":"matchPaymentPostingRemittance","summary":"Match remittance claims","description":"Runs local claim matching for one organization-owned remittance, updates local remittance-claim match state and remittance statistics, and returns aggregate matched/total counts.\n\n### When to use\nUse this after a remittance has imported claims but before staging payments, or when operators need to refresh local remittance-claim matching against QuickRCM claim records.\n\n### Before calling\nAuthenticate with `payment-posting:write` and use a `remittanceId` from the same organization. The request body has no public fields.\n\n### Request guidance\nPass `remittanceId` in the path and send `{}` or omit body fields. The endpoint performs local matching only; do not send raw ERA content, payer payloads, patient demographics, or direct claim-balance instructions.\n\n### Response semantics\nHTTP 200 returns action `MATCH_REMITTANCE_CLAIMS`, `remittanceId`, `matched`, `total`, and numeric `matchRate`. `matched` counts remittance claims in MATCHED or POSTED state after local matching. This is local match state, not payer adjudication or payment posting.\n\n### Errors and retries\nTreat 404 as a missing or wrong-organization remittance. Retry 429 with backoff. If a call times out, re-list or inspect local remittance state before retrying because local match state may already have changed.\n\n### Error notes\n- Treat 404 as a missing or wrong-organization remittance. Retry 429 with backoff. If a call times out, re-list or inspect local remittance state before retrying because local match state may already have changed.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"remittanceId","in":"path","description":"QuickRCM remittance identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"Pass `remittanceId` in the path and send `{}` or omit body fields. The endpoint performs local matching only; do not send raw ERA content, payer payloads, patient demographics, or direct claim-balance instructions."},"responses":{"200":{"description":"Organization-scoped match results.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"action":{"type":"string"},"mode":{"type":"string"},"externalRisk":{"type":"string"}},"required":["action","mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"action":"example-action","mode":"example-mode","externalRisk":"example-externalrisk"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/remittances/{remittanceId}/stage":{"post":{"operationId":"stagePaymentPostingRemittance","summary":"Validate payment staging","description":"Dry-runs payment staging for one organization-owned remittance and reports how many remittance claims are currently MATCHED.\n\n### When to use\nUse this after local matching to preview whether a remittance has matched claims ready for staging without creating Payment records.\n\n### Before calling\nAuthenticate with `payment-posting:write`, use a same-organization `remittanceId`, and keep `dryRun` true. The schema defaults `dryRun` to true.\n\n### Request guidance\nThe public handler accepts dry-run requests only. If `dryRun` is false, it returns 400. Do not document this endpoint as creating staged payments.\n\n### Response semantics\nHTTP 200 returns action `STAGE_PAYMENTS`, mode `DRY_RUN`, `matchedClaimCount`, an empty `stagedPaymentIds` array, and a warning that no Payment records were created.\n\n### Errors and retries\nFix 400 unsafe mode requests before retrying. Treat 404 as missing or wrong-tenant remittance context and 429 as a backoff signal.\n\n### Error notes\n- Fix 400 unsafe mode requests before retrying. Treat 404 as missing or wrong-tenant remittance context and 429 as a backoff signal.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"remittanceId","in":"path","description":"QuickRCM remittance identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":["boolean","null"],"default":true,"description":"Safe-mode flag for staging preview. It defaults to true and must remain true for this public endpoint."}}},"example":{"dryRun":true}}},"description":"The public handler accepts dry-run requests only. If `dryRun` is false, it returns 400. Do not document this endpoint as creating staged payments."},"responses":{"200":{"description":"Payment staging dry-run result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"action":{"type":"string"},"mode":{"type":"string"},"externalRisk":{"type":"string"}},"required":["action","mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"action":"example-action","mode":"example-mode","externalRisk":"example-externalrisk"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/remittances/{remittanceId}/confirm":{"post":{"operationId":"confirmPaymentPostingRemittance","summary":"Validate or queue payment posting confirmation","description":"Validates or safely simulates confirm-posting readiness for one organization-owned remittance by counting locally staged payments.\n\n### When to use\nUse this after internal or UI workflows have staged payments and an integration needs a public safe-mode check before operator review or downstream processing.\n\n### Before calling\nAuthenticate with `payment-posting:write` and use a same-organization `remittanceId`. Send `validateOnly: true` for validation mode or `queueOnly: true` for queue simulation; the defaults are `validateOnly: false` and `queueOnly: true`.\n\n### Request guidance\nThe public handler requires at least one of `validateOnly` or `queueOnly` to be true. It does not post payments, mutate claim balances, deduct credits, or create live queue work. Do not document `queueOnly` as actual job creation because the current response returns `queued: false`.\n\n### Response semantics\nHTTP 202 returns action `CONFIRM_PAYMENT_POSTING`, mode `VALIDATE_ONLY` or `QUEUE_ONLY`, `externalRisk: SIMULATED_ONLY`, `queued: false`, and `stagedPaymentCount`. It is local readiness metadata only.\n\n### Errors and retries\nFix 400 unsafe flag combinations before retrying. Treat 404 as missing or wrong-organization remittance. After timeouts, re-check local staged-payment state before retrying.\n\n### Error notes\n- Fix 400 unsafe flag combinations before retrying. Treat 404 as missing or wrong-organization remittance. After timeouts, re-check local staged-payment state before retrying.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"remittanceId","in":"path","description":"QuickRCM remittance identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":["boolean","null"],"default":false,"description":"Safe-mode flag for validation. When true, response mode is VALIDATE_ONLY and no live posting side effects occur."},"queueOnly":{"type":["boolean","null"],"default":true,"description":"Safe-mode flag for queue simulation. It defaults to true, but the current public response still returns `queued: false`."}}},"example":{"validateOnly":false,"queueOnly":true}}},"description":"The public handler requires at least one of `validateOnly` or `queueOnly` to be true. It does not post payments, mutate claim balances, deduct credits, or create live queue work. Do not document `queueOnly` as actual job creation because the current response returns `queued: false`."},"responses":{"202":{"description":"Confirm-posting request validated or accepted for safe queue simulation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"action":{"type":"string"},"mode":{"type":"string"},"externalRisk":{"type":"string"}},"required":["action","mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"action":"example-action","mode":"example-mode","externalRisk":"example-externalrisk"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/remittances/{remittanceId}/status":{"put":{"operationId":"updatePaymentPostingRemittanceStatus","summary":"Update remittance status","description":"Updates the local workflow status on one organization-owned remittance and returns the refreshed sanitized remittance summary.\n\n### When to use\nUse this endpoint when an integration or operator workflow needs to mark local remittance review, match, posting, or closure state without changing financial metadata.\n\n### Before calling\nAuthenticate with `payment-posting:write`, use a same-organization `remittanceId`, and choose one public remittance status enum value.\n\n### Request guidance\n`status` is required and must be PROCESSING, RECEIVED, MATCHED, PARTIALLY_MATCHED, UNMATCHED, REQUIRES_REVIEW, POSTED, PARTIALLY_POSTED, or CLOSED. Do not use this endpoint to post payments or modify claim balances.\n\n### Response semantics\nHTTP 200 returns `data.remittance`, the sanitized remittance summary after the status update. The status is local QuickRCM workflow state.\n\n### Errors and retries\nFix 400 invalid enum values before retrying. Treat 404 as missing or wrong-organization remittance. After timeouts, re-read the remittance before repeating the status update.\n\n### Error notes\n- Fix 400 invalid enum values before retrying. Treat 404 as missing or wrong-organization remittance. After timeouts, re-read the remittance before repeating the status update.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"remittanceId","in":"path","description":"QuickRCM remittance identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["PROCESSING","RECEIVED","MATCHED","PARTIALLY_MATCHED","UNMATCHED","REQUIRES_REVIEW","POSTED","PARTIALLY_POSTED","CLOSED"],"description":"Required local remittance workflow status to store on the remittance."}},"required":["status"]},"example":{"status":"PROCESSING"}}},"description":"`status` is required and must be PROCESSING, RECEIVED, MATCHED, PARTIALLY_MATCHED, UNMATCHED, REQUIRES_REVIEW, POSTED, PARTIALLY_POSTED, or CLOSED. Do not use this endpoint to post payments or modify claim balances."},"responses":{"200":{"description":"Updated remittance status.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"remittance":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"checkNumber":{"type":"string"},"checkDate":{"type":"string","format":"date-time"},"paymentMethod":{"type":"string"},"totalAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"payerName":{"type":"string"},"payerId":{"type":"string"},"status":{"type":"string","enum":["PROCESSING","RECEIVED","MATCHED","PARTIALLY_MATCHED","UNMATCHED","REQUIRES_REVIEW","POSTED","PARTIALLY_POSTED","CLOSED"]},"matchRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"overallConfidence":{"type":["string","null"],"enum":["HIGH","MEDIUM","LOW","NONE"]},"paymentCount":{"type":"integer","minimum":0},"remittanceClaimCount":{"type":"integer","minimum":0},"postedClaimCount":{"type":"integer","minimum":0},"unmatchedClaimCount":{"type":"integer","minimum":0},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","checkNumber","checkDate","paymentMethod","totalAmount","payerName","payerId","status","matchRate","overallConfidence","paymentCount","remittanceClaimCount","postedClaimCount","unmatchedClaimCount","createdAt"],"description":"Payment posting remittance summary. Raw 835 payloads and patient demographics are omitted."}},"required":["remittance"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"remittance":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","checkNumber":"example-checknumber","checkDate":"2026-06-08T10:15:30Z","paymentMethod":"example-paymentmethod","totalAmount":"example-totalamount","payerName":"Example payment_posting_remittance_statu","payerId":"87726","status":"PROCESSING","matchRate":"example-matchrate","overallConfidence":"HIGH","paymentCount":1,"remittanceClaimCount":1,"postedClaimCount":1,"unmatchedClaimCount":1,"createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/remittance-claims/{remittanceClaimId}/post-payment":{"post":{"operationId":"postPaymentPostingPayment","summary":"Validate direct payment posting","description":"Validates direct post-payment input against one organization-scoped remittance claim and returns a safe simulated acceptance response without creating Payment records or mutating claim balances.\n\n### When to use\nUse this when an integration wants QuickRCM to validate the shape and tenant ownership of proposed payment posting data before an internal or operator-controlled posting workflow.\n\n### Before calling\nAuthenticate with `payment-posting:write`, resolve `remittanceClaimId` from the same tenant, and send `validateOnly: true` unless intentionally testing queue simulation with `queueOnly: true`.\n\n### Request guidance\n`claimChargeAmount`, `paymentAmount`, `patientResponsibility`, and `claimStatusCode` are required. `linePayments` and `adjustments` default to empty arrays. Each line payment requires `claimLineId` and non-negative `paidAmount`; each adjustment requires `groupCode`, `reasonCode`, and `amount`. At least one of `validateOnly` or `queueOnly` must be true.\n\n### Response semantics\nHTTP 202 returns action `POST_PAYMENT`, mode `VALIDATE_ONLY` or `QUEUE_ONLY`, `externalRisk: SIMULATED_ONLY`, `accepted: true`, `queued: false`, and `remittanceClaimId`. It is not evidence of posted cash, claim-balance mutation, denial creation, patient balance creation, or credit deduction.\n\n### Errors and retries\nFix 400 validation failures, invalid amounts, missing required fields, or unsafe flag combinations before retrying. Treat 404 as missing or wrong-organization remittance claim. Use read-after-timeout before retrying because operator workflows may have changed local state.\n\n### Error notes\n- Fix 400 validation failures, invalid amounts, missing required fields, or unsafe flag combinations before retrying. Treat 404 as missing or wrong-organization remittance claim. Use read-after-timeout before retrying because operator workflows may have changed local state.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"remittanceClaimId","in":"path","description":"QuickRCM remittance-claim identifier in the path. It must belong to a remittance in the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":["boolean","null"],"default":true,"description":"Safe-mode flag that defaults to true. When true, response mode is VALIDATE_ONLY and no payment is created."},"queueOnly":{"type":["boolean","null"],"default":false,"description":"Safe-mode flag for queue simulation. It defaults to false, and the current public response still returns `queued: false`."},"claimChargeAmount":{"type":["number","null"],"minimum":0,"description":"Required non-negative claim charge amount for validation, supplied as a JSON number."},"paymentAmount":{"type":["number","null"],"minimum":0,"description":"Required non-negative proposed payment amount for validation, supplied as a JSON number."},"patientResponsibility":{"type":["number","null"],"minimum":0,"description":"Required non-negative proposed patient responsibility amount for validation."},"claimStatusCode":{"type":"string","minLength":1,"maxLength":16,"description":"Required ERA claim status code string, capped at 16 characters."},"linePayments":{"type":"array","items":{"type":"object","properties":{"claimLineId":{"type":"string","minLength":1,"description":"QuickRCM claim-line identifier referenced by a proposed line payment."},"paidAmount":{"type":["number","null"],"minimum":0,"description":"Non-negative proposed paid amount for a line payment."}},"required":["claimLineId","paidAmount"]},"default":[],"description":"Optional array of proposed line-level payment entries for validation."},"adjustments":{"type":"array","items":{"type":"object","properties":{"groupCode":{"type":"string","minLength":1,"maxLength":8,"description":"Adjustment group code such as CO, PR, OA, or PI; capped at 8 characters by the public schema."},"reasonCode":{"type":"string","minLength":1,"maxLength":16,"description":"Adjustment reason code string capped at 16 characters."},"amount":{"type":["number","null"],"description":"Adjustment amount supplied as a JSON number. The schema allows positive or negative finite values."}},"required":["groupCode","reasonCode","amount"]},"default":[],"description":"Optional array of proposed claim-level adjustment entries for validation."}},"required":["claimChargeAmount","paymentAmount","patientResponsibility","claimStatusCode"]},"example":{"claimChargeAmount":125.5,"paymentAmount":125.5,"patientResponsibility":1.25,"claimStatusCode":"example-claimstatuscode","validateOnly":true,"queueOnly":false,"linePayments":[],"adjustments":[]}}},"description":"`claimChargeAmount`, `paymentAmount`, `patientResponsibility`, and `claimStatusCode` are required. `linePayments` and `adjustments` default to empty arrays. Each line payment requires `claimLineId` and non-negative `paidAmount`; each adjustment requires `groupCode`, `reasonCode`, and `amount`. At least one of `validateOnly` or `queueOnly` must be true."},"responses":{"202":{"description":"Post-payment request validated for safe simulation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"action":{"type":"string"},"mode":{"type":"string"},"externalRisk":{"type":"string"}},"required":["action","mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"action":"example-action","mode":"example-mode","externalRisk":"example-externalrisk"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/payers/refresh":{"post":{"operationId":"refreshPaymentPostingPayers","summary":"Dry-run payer ID refresh","description":"Finds organization-owned remittances whose local `payerId` is `UNKNOWN` and returns sanitized refresh candidates without fetching files or parsing EDI payloads.\n\n### When to use\nUse this endpoint to preview payer-ID cleanup candidates before an internal or operator-controlled refresh workflow.\n\n### Before calling\nAuthenticate with `payment-posting:write`. Keep `dryRun` true for preview mode or set `queueOnly` true for queue simulation. Use `take` to bound the candidate scan.\n\n### Request guidance\n`dryRun` defaults to true, `queueOnly` defaults to false, and `take` defaults to 50 with a maximum of 50. At least one of `dryRun` or `queueOnly` must be true. Do not document this public wrapper as reading S3 objects or parsing ERA files.\n\n### Response semantics\nHTTP 200 returns action `REFRESH_PAYER_IDS`, mode `DRY_RUN` or `QUEUE_ONLY`, `externalRisk: SIMULATED_ONLY`, `queued: false`, `candidateCount`, and candidate id/payerName/checkNumber triples. Storage file details are selected internally but intentionally omitted from the public response.\n\n### Errors and retries\nFix 400 unsafe flag combinations or invalid `take` values before retrying. Treat 429 as a backoff signal. Because this is a preview/simulation endpoint, retry transient 5xx failures with the same bounded `take`.\n\n### Error notes\n- Fix 400 unsafe flag combinations or invalid `take` values before retrying. Treat 429 as a backoff signal. Because this is a preview/simulation endpoint, retry transient 5xx failures with the same bounded `take`.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":["boolean","null"],"default":true,"description":"Safe-mode flag for preview mode. It defaults to true."},"queueOnly":{"type":["boolean","null"],"default":false,"description":"Safe-mode flag for queue simulation. Current public handler still returns `queued: false`."},"take":{"type":"integer","minimum":1,"maximum":50,"default":50,"description":"Maximum candidate remittances to inspect and return. Defaults to 50 and cannot exceed 50."}}},"example":{"dryRun":true,"queueOnly":false,"take":50}}},"description":"`dryRun` defaults to true, `queueOnly` defaults to false, and `take` defaults to 50 with a maximum of 50. At least one of `dryRun` or `queueOnly` must be true. Do not document this public wrapper as reading S3 objects or parsing ERA files."},"responses":{"200":{"description":"Payer refresh dry-run candidates.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"action":{"type":"string"},"mode":{"type":"string"},"externalRisk":{"type":"string"}},"required":["action","mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"action":"example-action","mode":"example-mode","externalRisk":"example-externalrisk"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/payment-posting/remittances/{remittanceId}/finalize":{"post":{"operationId":"finalizePaymentPostingRemittance","summary":"Validate remittance finalization","description":"Validates or safely simulates public remittance finalization for one organization-owned remittance without invoking internal HMAC worker endpoints.\n\n### When to use\nUse this after matching, staging, or review workflows when an integration needs public safe-mode finalization readiness metadata.\n\n### Before calling\nAuthenticate with `payment-posting:write`, use a same-organization `remittanceId`, and send `validateOnly: true` or `queueOnly: true`. `validateOnly` defaults to true.\n\n### Request guidance\nThe handler rejects requests where both `validateOnly` and `queueOnly` are false. Do not document this public wrapper as closing remittances, posting cash, calling internal worker APIs, or changing claim balances.\n\n### Response semantics\nHTTP 202 returns action `FINALIZE_REMITTANCE`, mode `VALIDATE_ONLY` or `QUEUE_ONLY`, `externalRisk: SIMULATED_ONLY`, `queued: false`, and `remittanceClaimCount`. It is readiness/simulation metadata only.\n\n### Errors and retries\nFix 400 unsafe flag combinations before retrying. Treat 404 as missing or wrong-organization remittance. After a timeout, re-read remittance state and claim counts before retrying.\n\n### Error notes\n- Fix 400 unsafe flag combinations before retrying. Treat 404 as missing or wrong-organization remittance. After a timeout, re-read remittance state and claim counts before retrying.\n","tags":["Payment Posting"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"remittanceId","in":"path","description":"QuickRCM remittance identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":["boolean","null"],"default":true,"description":"Safe-mode flag that defaults to true. When true, response mode is VALIDATE_ONLY and no finalization side effects occur."},"queueOnly":{"type":["boolean","null"],"default":false,"description":"Safe-mode flag for queue simulation. It defaults to false, and current public queue simulation still returns `queued: false`."}}},"example":{"validateOnly":true,"queueOnly":false}}},"description":"The handler rejects requests where both `validateOnly` and `queueOnly` are false. Do not document this public wrapper as closing remittances, posting cash, calling internal worker APIs, or changing claim balances."},"responses":{"202":{"description":"Remittance finalization request validated for safe simulation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"action":{"type":"string"},"mode":{"type":"string"},"externalRisk":{"type":"string"}},"required":["action","mode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"action":"example-action","mode":"example-mode","externalRisk":"example-externalrisk"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested payment posting resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/alerts":{"get":{"operationId":"listPreventionAlerts","summary":"List prevention alerts","description":"Lists prevention claim-creation alerts owned by the authenticated organization, with filters for lifecycle status, severity, alert type, claim, claim line, user, created date range, and pagination.\n\n### When to use\nUse this endpoint to populate a prevention alert inbox, reconcile active warnings for claim review, or retrieve dismissed and acknowledged alerts for audit workflows.\n\n### Before calling\nAuthenticate with a Prevention read or write scope. Decide whether to filter by `status`, `severity`, `alertType`, claim context, user, and `startDate`/`endDate`; broad alert lists can expose claim-adjacent operational context.\n\n### Request guidance\nUse `take` between 1 and 100 and `skip` between 0 and 10000. `startDate` and `endDate` must be ISO date-time strings. Do not send `organizationId`; the API key selects the tenant.\n\n### Request notes\n- `status` is one of the source-backed lifecycle values: `ACTIVE`, `ACKNOWLEDGED`, `DISMISSED`, `RESOLVED`, or `EXPIRED`.\n- `severity` is one of `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.\n- `take` defaults to 25 and is capped at 100.\n\n### Response semantics\nHTTP 200 returns `data.alerts`, `total`, `skip`, and `take`. Each alert includes local prevention status, severity, title, message, suggested action, decimal strings for estimated risk and historical denial rate when present, and a sanitized claim summary with payer identifiers. It does not include patient demographics or raw claim payloads.\n\n### Response notes\n- `estimatedRiskAmount` and `historicalDenialRate` are decimal strings or null, not floating-point numbers.\n- `status` is derived from `wasActedUpon`, `wasDismissed`, `acknowledgedAt`, `dismissedAt`, `resolvedAt`, and `dueAt`.\n- `claim` is nullable and only contains the sanitized claim id, status, claim control number, and payer summary.\n- Use alert action or dismissal endpoints to change alert workflow state.\n\n### Errors and retries\nTreat 400 as invalid filters, 401/403 as credential or scope issues, and 429 as rate limiting that requires backoff. Retry transient 5xx failures after checking whether the client already has a fresh page.\n\n### Error notes\n- 403 means the API key lacks Prevention read/write scope.\n- Do not retry malformed date-time or pagination parameters unchanged.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["ACTIVE","ACKNOWLEDGED","DISMISSED","RESOLVED","EXPIRED"]},"required":false,"name":"status","in":"query","description":"Optional alert lifecycle filter from source constants: `ACTIVE`, `ACKNOWLEDGED`, `DISMISSED`, `RESOLVED`, or `EXPIRED`. `EXPIRED` means the alert is past `dueAt` and is not dismissed or resolved."},{"schema":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"required":false,"name":"severity","in":"query","description":"Optional alert severity filter from `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"alertType","in":"query","description":"Organization-local alert classification such as a pre-submission scrub or claim creation warning."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"claimId","in":"query","description":"QuickRCM claim identifier used to filter alerts. The claim must belong to the API key organization."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"claimLineId","in":"query","description":"Optional claim line identifier used to filter line-specific prevention alerts."},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"userId","in":"query","description":"QuickRCM user identifier associated with the alert."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"startDate","in":"query","description":"Inclusive created-at lower bound as an ISO date-time string."},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"endDate","in":"query","description":"Inclusive created-at upper bound as an ISO date-time string."},{"schema":{"type":["integer","null"],"minimum":0,"maximum":10000,"default":0},"required":false,"name":"skip","in":"query","description":"Number of records to skip for pagination. Use with take when the endpoint exposes skip/take pagination."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"take","in":"query","description":"Maximum number of records to take for skip/take pagination."}],"responses":{"200":{"description":"Prevention alert list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"alerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":["string","null"]},"claimLineId":{"type":["string","null"]},"userId":{"type":"string"},"alertType":{"type":"string"},"triggerSource":{"type":"string"},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"status":{"type":"string","enum":["ACTIVE","ACKNOWLEDGED","DISMISSED","RESOLVED","EXPIRED"]},"title":{"type":"string"},"message":{"type":"string"},"suggestedAction":{"type":["string","null"]},"estimatedRiskAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"historicalDenialRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"wasActedUpon":{"type":"boolean"},"actionTaken":{"type":["string","null"]},"wasDismissed":{"type":"boolean"},"dismissReason":{"type":["string","null"]},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"ownerUserId":{"type":["string","null"]},"dueAt":{"type":["string","null"],"format":"date-time"},"resolutionCode":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"claim":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":["string","null"]},"claimControlNumber":{"type":["string","null"]},"payer":{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"payerId":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","payerId","name"]}},"required":["id","status","claimControlNumber","payer"]}},"required":["id","organizationId","claimId","claimLineId","userId","alertType","triggerSource","severity","status","title","message","suggestedAction","estimatedRiskAmount","historicalDenialRate","wasActedUpon","actionTaken","wasDismissed","dismissReason","acknowledgedAt","dismissedAt","resolvedAt","ownerUserId","dueAt","resolutionCode","createdAt","claim"]}},"total":{"type":"integer","minimum":0},"skip":{"type":"integer","minimum":0},"take":{"type":"integer","minimum":1}},"required":["alerts","total","skip","take"]}},"required":["success","data"]},"example":{"success":true,"data":{"alerts":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","claimLineId":"00000000-0000-4000-8000-000000000001","userId":"00000000-0000-4000-8000-000000000001","alertType":"example-alerttype","triggerSource":"example-triggersource","severity":"LOW","status":"ACTIVE","title":"Example prevention_alert","message":"Request failed","suggestedAction":"example-suggestedaction","estimatedRiskAmount":"example-estimatedriskamount","historicalDenialRate":"example-historicaldenialrate","wasActedUpon":true,"actionTaken":"example-actiontaken","wasDismissed":true,"dismissReason":"example-dismissreason","acknowledgedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","ownerUserId":"00000000-0000-4000-8000-000000000001","dueAt":"2026-06-08T10:15:30Z","resolutionCode":"example-resolutioncode","createdAt":"2026-06-08T10:15:30Z","claim":{"id":"00000000-0000-4000-8000-000000000001","status":"active","claimControlNumber":"example-claimcontrolnumber","payer":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","name":"Example prevention_alert"}}}],"total":1,"skip":1,"take":1}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/alerts/{alertId}":{"get":{"operationId":"getPreventionAlert","summary":"Get prevention alert","description":"Returns one prevention alert after verifying that `alertId` belongs to the authenticated organization.\n\n### When to use\nUse this endpoint when a list response, work queue, or integration event gives you a specific prevention alert to inspect before taking action.\n\n### Before calling\nUse an `alertId` from a trusted QuickRCM response in the same tenant context. Do not guess alert identifiers across organizations.\n\n### Request guidance\nPass only the path `alertId`. This endpoint does not need a request body or organization selector.\n\n### Request notes\n- `alertId` is required and must be non-empty.\n- The bearer API key selects the organization.\n\n### Response semantics\nHTTP 200 returns `data.alert` with the same sanitized alert shape used by the list endpoint. A nullable `claim` summary may be included; patient demographics and raw claim payloads are not returned.\n\n### Response notes\n- `data.alert.status` is derived from the alert lifecycle fields, including acknowledgment, dismissal, resolution, and due-date state.\n- `claim` can be null when the alert is not attached to a current claim summary.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization alert context. Retry transient server failures with backoff, but do not retry authorization failures without changing credentials or scope.\n\n### Error notes\n- 404 can mean the alert does not exist or belongs to another organization.\n- 403 means the API key lacks Prevention read/write scope.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"alertId","in":"path","description":"QuickRCM prevention alert identifier in the path. It must belong to the authenticated organization."}],"responses":{"200":{"description":"Prevention alert","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"alert":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":["string","null"]},"claimLineId":{"type":["string","null"]},"userId":{"type":"string"},"alertType":{"type":"string"},"triggerSource":{"type":"string"},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"status":{"type":"string","enum":["ACTIVE","ACKNOWLEDGED","DISMISSED","RESOLVED","EXPIRED"]},"title":{"type":"string"},"message":{"type":"string"},"suggestedAction":{"type":["string","null"]},"estimatedRiskAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"historicalDenialRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"wasActedUpon":{"type":"boolean"},"actionTaken":{"type":["string","null"]},"wasDismissed":{"type":"boolean"},"dismissReason":{"type":["string","null"]},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"ownerUserId":{"type":["string","null"]},"dueAt":{"type":["string","null"],"format":"date-time"},"resolutionCode":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"claim":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":["string","null"]},"claimControlNumber":{"type":["string","null"]},"payer":{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"payerId":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","payerId","name"]}},"required":["id","status","claimControlNumber","payer"]}},"required":["id","organizationId","claimId","claimLineId","userId","alertType","triggerSource","severity","status","title","message","suggestedAction","estimatedRiskAmount","historicalDenialRate","wasActedUpon","actionTaken","wasDismissed","dismissReason","acknowledgedAt","dismissedAt","resolvedAt","ownerUserId","dueAt","resolutionCode","createdAt","claim"]}},"required":["alert"]}},"required":["success","data"]},"example":{"success":true,"data":{"alert":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","claimLineId":"00000000-0000-4000-8000-000000000001","userId":"00000000-0000-4000-8000-000000000001","alertType":"example-alerttype","triggerSource":"example-triggersource","severity":"LOW","status":"ACTIVE","title":"Example prevention_alert","message":"Request failed","suggestedAction":"example-suggestedaction","estimatedRiskAmount":"example-estimatedriskamount","historicalDenialRate":"example-historicaldenialrate","wasActedUpon":true,"actionTaken":"example-actiontaken","wasDismissed":true,"dismissReason":"example-dismissreason","acknowledgedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","ownerUserId":"00000000-0000-4000-8000-000000000001","dueAt":"2026-06-08T10:15:30Z","resolutionCode":"example-resolutioncode","createdAt":"2026-06-08T10:15:30Z","claim":{"id":"00000000-0000-4000-8000-000000000001","status":"active","claimControlNumber":"example-claimcontrolnumber","payer":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","name":"Example prevention_alert"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention alert not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"acknowledgePreventionAlert","summary":"Acknowledge prevention alert","description":"Acknowledges an organization-owned prevention alert or dismisses it when `dismiss` is true.\n\n### When to use\nUse this endpoint for the lightweight alert update path when a reviewer has seen the alert, recorded a short action, or wants to dismiss it from the active alert queue.\n\n### Before calling\nAuthenticate with Prevention write scope and load the alert from the same organization. Decide whether this is an acknowledgment or dismissal because `dismiss: true` changes the update path.\n\n### Request guidance\nSend `actionTaken` for an acknowledgment. Send `dismiss: true` with optional `dismissReason` for dismissal. The source request schema accepts optional `resolutionCode`; current handler persists it on the dismiss path and defaults dismissal resolution to `DISMISSED` when omitted.\n\n### Request notes\n- `actionTaken` and `dismissReason` are capped at 1000 characters.\n- `dismiss` defaults to false.\n- `resolutionCode` is optional and capped at 100 characters.\n- Keep action text free of unnecessary protected health information (PHI), raw payer payloads, credentials, and electronic data interchange (EDI).\n\n### Response semantics\nHTTP 200 returns the updated `data.alert` object. The update is local QuickRCM workflow state; it does not alter the claim or send payer communications.\n\n### Response notes\n- Acknowledgment sets acted-upon state in local alert workflow.\n- Dismissal sets dismissed state, stores the optional dismissal reason, sets `dismissedAt`, and stores `resolutionCode` or default `DISMISSED`.\n\n### Errors and retries\nFix 400 validation errors before retrying. Treat 404 as missing or wrong-tenant alert. If a retry follows a network timeout, re-read the alert first because the previous update may have completed.\n\n### Error notes\n- 403 means the API key lacks Prevention write scope.\n- 404 means the alert was not found in the authenticated organization.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"alertId","in":"path","description":"QuickRCM prevention alert identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"actionTaken":{"type":"string","minLength":1,"maxLength":1000,"description":"Short staff or system action note for an acknowledgment. Avoid patient details and secrets."},"dismiss":{"type":"boolean","default":false,"description":"When true, the handler dismisses the alert instead of recording an acknowledgment."},"dismissReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional dismissal rationale, capped at 1000 characters."},"resolutionCode":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local resolution code accepted by the source schema. Current handler stores it when `dismiss` is true; use the action endpoint when completing an alert with an `ACTION_TAKEN` style code."}}},"example":{"actionTaken":"example-actiontaken","dismiss":false,"dismissReason":"example-dismissreason","resolutionCode":"example-resolutioncode"}}},"description":"Send `actionTaken` for an acknowledgment. Send `dismiss: true` with optional `dismissReason` for dismissal. The source request schema accepts optional `resolutionCode`; current handler persists it on the dismiss path and defaults dismissal resolution to `DISMISSED` when omitted."},"responses":{"200":{"description":"Prevention alert updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"alert":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":["string","null"]},"claimLineId":{"type":["string","null"]},"userId":{"type":"string"},"alertType":{"type":"string"},"triggerSource":{"type":"string"},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"status":{"type":"string","enum":["ACTIVE","ACKNOWLEDGED","DISMISSED","RESOLVED","EXPIRED"]},"title":{"type":"string"},"message":{"type":"string"},"suggestedAction":{"type":["string","null"]},"estimatedRiskAmount":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"historicalDenialRate":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"wasActedUpon":{"type":"boolean"},"actionTaken":{"type":["string","null"]},"wasDismissed":{"type":"boolean"},"dismissReason":{"type":["string","null"]},"acknowledgedAt":{"type":["string","null"],"format":"date-time"},"dismissedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"ownerUserId":{"type":["string","null"]},"dueAt":{"type":["string","null"],"format":"date-time"},"resolutionCode":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"claim":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":["string","null"]},"claimControlNumber":{"type":["string","null"]},"payer":{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"payerId":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","payerId","name"]}},"required":["id","status","claimControlNumber","payer"]}},"required":["id","organizationId","claimId","claimLineId","userId","alertType","triggerSource","severity","status","title","message","suggestedAction","estimatedRiskAmount","historicalDenialRate","wasActedUpon","actionTaken","wasDismissed","dismissReason","acknowledgedAt","dismissedAt","resolvedAt","ownerUserId","dueAt","resolutionCode","createdAt","claim"]}},"required":["alert"]}},"required":["success","data"]},"example":{"success":true,"data":{"alert":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","claimLineId":"00000000-0000-4000-8000-000000000001","userId":"00000000-0000-4000-8000-000000000001","alertType":"example-alerttype","triggerSource":"example-triggersource","severity":"LOW","status":"ACTIVE","title":"Example acknowledge_prevention_alert","message":"Request failed","suggestedAction":"example-suggestedaction","estimatedRiskAmount":"example-estimatedriskamount","historicalDenialRate":"example-historicaldenialrate","wasActedUpon":true,"actionTaken":"example-actiontaken","wasDismissed":true,"dismissReason":"example-dismissreason","acknowledgedAt":"2026-06-08T10:15:30Z","dismissedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","ownerUserId":"00000000-0000-4000-8000-000000000001","dueAt":"2026-06-08T10:15:30Z","resolutionCode":"example-resolutioncode","createdAt":"2026-06-08T10:15:30Z","claim":{"id":"00000000-0000-4000-8000-000000000001","status":"active","claimControlNumber":"example-claimcontrolnumber","payer":{"id":"00000000-0000-4000-8000-000000000001","payerId":"87726","name":"Example acknowledge_prevention_alert"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention alert not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/claims/{claimId}/scrub":{"post":{"operationId":"scrubPreventionClaim","summary":"Queue a prevention claim scrub","description":"Validates an organization-owned claim and either validates, simulates, or queues a local prevention scrub work item.\n\n### When to use\nUse this endpoint when an external workflow wants QuickRCM to prepare a claim for pre-submission prevention review without calling a payer or external system.\n\n### Before calling\nAuthenticate with Prevention write scope. Use a `claimId` from the same organization and decide whether the request should be `validateOnly`, `dryRun`, or queued.\n\n### Request guidance\nSafe-mode precedence is `validateOnly` first, then `dryRun`, otherwise `queueOnly`. In queue mode the current handler creates or reuses a `PENDING_SCRUB` PreventionWorkItem. Reuse `idempotencyKey` only for the same claim and same logical retry.\n\n### Request notes\n- `queueOnly` defaults to true.\n- `validateOnly` wins over `dryRun` if both are true.\n- `idempotencyKey` is capped at 200 characters and is matched against existing public work item metadata in queue mode.\n- Passthrough body properties are not documented public contract fields and must not carry PHI, raw claim payloads, raw EDI, vendor payloads, credentials, or tokens.\n\n### Response semantics\nHTTP 200 returns a workflow result. `VALIDATED` means no work item was queued; `QUEUED` means a local work item was created or reused. `externalDispatch` is false and no payer or large language model (LLM) output is returned.\n\n### Response notes\n- `mode` echoes `validateOnly`, `dryRun`, or `queueOnly`.\n- `workItemId` and `idempotentReplay` are present when queue mode creates or reuses a work item.\n- `externalDispatch` is false.\n\n### Errors and retries\nFix 400 validation errors before retrying. Treat 404 as missing or wrong-organization claim. If queue mode times out, retry with the same `idempotencyKey` to reuse an existing matching work item when present.\n\n### Error notes\n- 404 means the claim did not resolve in the API key organization.\n- 429 requires backoff and a safe retry strategy.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier in the path. The claim must belong to the API key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Default true. When no higher-precedence safety flag is set, queues a local `PENDING_SCRUB` work item."},"validateOnly":{"type":"boolean","default":false,"description":"Highest-precedence safety flag. Validates ownership and request shape without queueing."},"dryRun":{"type":"boolean","default":false,"description":"Second-precedence safety flag. Simulates the request without queueing."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller retry key used in queue mode to find an existing matching public work item. Do not include protected health information (PHI)."}}},"example":{"queueOnly":true,"validateOnly":false,"dryRun":false,"idempotencyKey":"example-idempotencykey"}}},"description":"Safe-mode precedence is `validateOnly` first, then `dryRun`, otherwise `queueOnly`. In queue mode the current handler creates or reuses a `PENDING_SCRUB` PreventionWorkItem. Reuse `idempotencyKey` only for the same claim and same logical retry."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/claims/batch-scrub":{"post":{"operationId":"batchScrubPreventionClaims","summary":"Queue prevention claim scrubs in batch","description":"Validates a bounded batch of organization-owned claims and either validates, simulates, or queues local prevention scrub work items for them.\n\n### When to use\nUse this endpoint for scheduled or bulk prevention review of known claim IDs, or for a bounded status-based batch such as draft claims needing scrub review.\n\n### Before calling\nAuthenticate with Prevention write scope. Provide up to 100 `claimIds` when you need exact records, or use the optional `status` filter to select up to 100 organization-owned claims.\n\n### Request guidance\nIf `claimIds` is supplied, every ID must resolve in the organization or the request returns 404. Without `claimIds`, the current handler searches by the supplied `status`, defaulting to `DRAFT`, and takes up to 100 claims. Safe-mode precedence is `validateOnly`, then `dryRun`, otherwise queue mode.\n\n### Request notes\n- `claimIds` has a maximum of 100 IDs.\n- `status` is a free-form claim status string in the generated schema; default handler behavior uses `DRAFT` when omitted.\n- A single `idempotencyKey` is applied to each queued work item in the batch metadata.\n- Passthrough body properties are not documented public contract fields and must not carry PHI, raw claim payloads, raw EDI, vendor payloads, credentials, or tokens.\n\n### Response semantics\nHTTP 200 returns the batch workflow result with matched `claimIds`, `total`, mode, and `externalDispatch: false`. Queue mode returns `workItems` when claims were matched; a queue-mode request with zero matches returns `VALIDATED` and no work items.\n\n### Response notes\n- `total` is the number of matched claims.\n- `workItems` appears only when local queueing created or reused work items.\n- `externalDispatch` is false.\n\n### Errors and retries\nFix invalid body shape or too many claim IDs before retrying. Treat 404 as at least one explicit claim ID not being owned by the organization. Use the same `idempotencyKey` only for retrying the same batch intent.\n\n### Error notes\n- 404 with explicit `claimIds` means one or more claims were not found for the organization.\n- Do not retry a malformed or oversized batch unchanged.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Default true. When neither `validateOnly` nor `dryRun` is true, queues local `PENDING_SCRUB` work items for each matched organization-owned claim."},"validateOnly":{"type":"boolean","default":false,"description":"Highest-precedence safety flag. Validates batch request shape and matched organization-owned claims without queueing work items."},"dryRun":{"type":"boolean","default":false,"description":"Second-precedence safety flag. Simulates the batch request without queueing work items."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional retry key applied to each queued work item in batch metadata. It is capped at 200 characters and must not contain protected health information (PHI) or secrets."},"claimIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Optional array of up to 100 QuickRCM claim identifiers that must all belong to the authenticated organization."},"status":{"type":"string","minLength":1,"maxLength":100,"description":"Optional claim status filter used when `claimIds` is omitted. Current handler defaults to `DRAFT`."}}},"example":{"queueOnly":true,"validateOnly":false,"dryRun":false,"idempotencyKey":"example-idempotencykey","claimIds":["example-claimids"],"status":"active"}}},"description":"If `claimIds` is supplied, every ID must resolve in the organization or the request returns 404. Without `claimIds`, the current handler searches by the supplied `status`, defaulting to `DRAFT`, and takes up to 100 claims. Safe-mode precedence is `validateOnly`, then `dryRun`, otherwise queue mode."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/claims/{claimId}/clear":{"post":{"operationId":"clearPreventionClaim","summary":"Clear a scrubbed claim for submission","description":"Marks the latest organization-scoped scrub for a claim as cleared for submission when the clear gate allows it.\n\n### When to use\nUse this endpoint after findings have been reviewed or resolved and the claim should be allowed to proceed through submission workflows.\n\n### Before calling\nAuthenticate with Prevention write scope. Ensure the claim has a scrub result in the organization and that blocking findings are resolved.\n\n### Request guidance\nSet `forceOverride: true` only to acknowledge remaining warning-level findings that require override. Critical or high blocking findings still must be resolved first under current service behavior.\n\n### Request notes\n- `forceOverride` defaults to false.\n- Do not use `forceOverride` as a bypass for critical or high unresolved findings.\n\n### Response semantics\nHTTP 200 returns `status: CLEARED` with the updated scrub record in the generic workflow envelope. Clearing affects local prevention state; it is not a payer submission.\n\n### Response notes\n- `status` is `CLEARED` on success.\n- `scrub` is returned as a generic serialized local record.\n\n### Errors and retries\n400 can mean critical/high findings remain or warning findings need `forceOverride`. 404 means no scrub result was found for the claim in the organization. Re-read scrub findings before retrying.\n\n### Error notes\n- 400 can indicate unresolved blocking findings.\n- 404 means no latest scrub exists for the claim in the organization.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier whose latest prevention scrub should be cleared."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"forceOverride":{"type":"boolean","default":false,"description":"Acknowledges remaining warning-level findings when true. It does not bypass critical or high blockers."}}},"example":{"forceOverride":false}}},"description":"Set `forceOverride: true` only to acknowledge remaining warning-level findings that require override. Critical or high blocking findings still must be resolved first under current service behavior."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/claims/{claimId}/recall":{"post":{"operationId":"recallPreventionClaim","summary":"Recall a cleared claim","description":"Moves a recently cleared organization-owned claim scrub back into prevention review.\n\n### When to use\nUse this endpoint when a claim was cleared prematurely and should be reviewed again before submission proceeds.\n\n### Before calling\nAuthenticate with Prevention write scope. Confirm that the latest scrub for the claim is currently cleared and still within the recall window enforced by the workflow service.\n\n### Request guidance\nSend an optional `reason` up to 1000 characters. Keep it operational and sanitized.\n\n### Request notes\n- `reason` is optional and capped at 1000 characters.\n- Current tests cover a five-minute recall window for recently cleared scrubs.\n\n### Response semantics\nHTTP 200 returns `status: RECALLED`, the optional reason, and the updated scrub in the generic workflow envelope. The endpoint does not modify payer status or external submissions.\n\n### Response notes\n- `status` is `RECALLED` on success.\n- `scrub.isCleared` should be false after a successful recall.\n\n### Errors and retries\n400 can mean the latest scrub is not cleared or the recall window elapsed. 404 means no scrub result exists in the organization. Re-read scrub state before retrying.\n\n### Error notes\n- 400 can indicate the claim was not cleared or is outside the recall window.\n- 404 means no org-scoped scrub was found.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"QuickRCM claim identifier whose latest cleared scrub should be recalled."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional recall rationale. Avoid protected health information (PHI) and secrets."}}},"example":{"reason":"example-reason"}}},"description":"Send an optional `reason` up to 1000 characters. Keep it operational and sanitized."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/findings/{findingId}/status":{"put":{"operationId":"resolvePreventionFinding","summary":"Resolve a prevention finding","description":"Updates the workflow status and resolution metadata for an organization-owned pre-submission finding.\n\n### When to use\nUse this endpoint after a reviewer has acknowledged, fixed, overridden, or marked a prevention finding as a false positive.\n\n### Before calling\nAuthenticate with Prevention write scope and use a `findingId` from a scrub owned by the API key organization.\n\n### Request guidance\nSend one of the generated statuses: `ACKNOWLEDGED`, `FIXED`, `OVERRIDDEN`, or `FALSE_POSITIVE`. Include `overrideReason` when overriding or when an audit explanation is useful.\n\n### Request notes\n- `overrideReason` is optional and capped at 1000 characters.\n\n### Response semantics\nHTTP 200 returns `status: UPDATED` and a serialized local finding in the generic workflow envelope. This endpoint does not automatically clear the claim; use `clearPreventionClaim` separately when appropriate.\n\n### Response notes\n- `finding` is a generic local record in current handler behavior.\n- `resolvedBy` and `resolvedAt` are set by the handler.\n\n### Errors and retries\n400 means invalid status or reason shape. 404 means the finding did not resolve through an organization-scoped scrub. Re-read the finding before retrying an ambiguous update.\n\n### Error notes\n- 404 means the finding is absent or not attached to a scrub in the API key organization.\n- Do not retry invalid enum values unchanged.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"findingId","in":"path","description":"QuickRCM pre-submission finding identifier. Its parent scrub must belong to the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ACKNOWLEDGED","FIXED","OVERRIDDEN","FALSE_POSITIVE"],"description":"Required finding resolution status: `ACKNOWLEDGED`, `FIXED`, `OVERRIDDEN`, or `FALSE_POSITIVE`."},"overrideReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional explanation for an override or resolution decision."},"overrideReasonCode":{"type":"string","enum":["PROVIDER_DIRECTED","PRIOR_AUTH_ON_FILE","EMERGENCY_SERVICES","DOCUMENTATION_ATTACHED","OTHER"]}},"required":["status"]},"example":{"status":"ACKNOWLEDGED","overrideReason":"example-overridereason","overrideReasonCode":"PROVIDER_DIRECTED"}}},"description":"Send one of the generated statuses: `ACKNOWLEDGED`, `FIXED`, `OVERRIDDEN`, or `FALSE_POSITIVE`. Include `overrideReason` when overriding or when an audit explanation is useful."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/findings/{findingId}/auto-fix/preview":{"post":{"operationId":"previewPreventionAutoFix","summary":"Preview a prevention auto-fix","description":"Builds a local auto-fix preview for an eligible organization-owned prevention finding without mutating claim line data.\n\n### When to use\nUse this endpoint before applying an auto-fix so a reviewer can inspect the proposed deterministic change.\n\n### Before calling\nAuthenticate with Prevention write scope. Use a finding that belongs to an org-scoped scrub and is eligible for automatic fixing.\n\n### Request guidance\nThe generated body only exposes `validateOnly`. Current service evidence supports auto-fix rollback metadata for Medically Unlikely Edit (MUE) quantity reductions; other finding types can return 400.\n\n### Request notes\n- `validateOnly` defaults to false.\n- Only documented eligible auto-fix types should be presented as previewable.\n- Do not include protected health information (PHI) in any future metadata around preview requests.\n\n### Response semantics\nHTTP 200 returns `status: PREVIEW`, an `autoFixRun` preview record, and a `diff` in the generic workflow envelope. It records preview metadata but does not update the claim line quantity.\n\n### Response notes\n- `diff` currently describes the proposed local field change.\n- Preview is not the same as apply; claim data is not mutated by preview.\n\n### Errors and retries\n400 can mean the finding type is not eligible, rollback metadata is unsupported, or the suggested value is invalid. 404 means the finding or claim line was not found in the organization.\n\n### Error notes\n- 400 often indicates the finding is not auto-fix eligible.\n- 404 means the org-scoped finding or claim line could not be found.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"findingId","in":"path","description":"QuickRCM pre-submission finding identifier selected for auto-fix preview."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","default":false,"description":"Optional flag included in public metadata; preview itself does not mutate claim data."}}},"example":{"validateOnly":false}}},"description":"The generated body only exposes `validateOnly`. Current service evidence supports auto-fix rollback metadata for Medically Unlikely Edit (MUE) quantity reductions; other finding types can return 400."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/findings/{findingId}/auto-fix/apply":{"post":{"operationId":"applyPreventionAutoFix","summary":"Apply a prevention auto-fix","description":"Applies an approved local auto-fix for an eligible organization-owned prevention finding.\n\n### When to use\nUse this endpoint after a reviewer has approved the deterministic patch shown in an auto-fix preview.\n\n### Before calling\nAuthenticate with Prevention write scope. Confirm the finding is eligible and that the reviewer has approved the change.\n\n### Request guidance\n`approvalReason` is required and capped at 1000 characters. Keep the reason operational and sanitized. Current service evidence applies Medically Unlikely Edit (MUE) quantity reductions and records snapshots for rollback.\n\n### Request notes\n- `approvalReason` is required.\n- Current public auto-fix role is manager-level in the handler.\n- Do not present this endpoint as supporting every finding type.\n\n### Response semantics\nHTTP 200 returns `status: APPLIED` and an `autoFixRun` record. Current handler updates the claim line quantity for supported Medically Unlikely Edit (MUE) quantity fixes and marks the finding fixed with the approval reason.\n\n### Response notes\n- `status` is `APPLIED` on success.\n- `autoFixRun` stores before/after snapshots for supported rollback.\n\n### Errors and retries\n400 can mean missing approval reason, ineligible finding type, unsupported rollback metadata, or invalid suggested quantity. Re-read the finding and auto-fix run before retrying after an ambiguous timeout because the claim line may already be updated.\n\n### Error notes\n- 400 can mean the finding cannot be automatically fixed.\n- 404 can mean the finding or claim line was not found in the organization.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"findingId","in":"path","description":"QuickRCM pre-submission finding identifier selected for auto-fix application."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"approvalReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Required human or system approval explanation for the local fix."}},"required":["approvalReason"]},"example":{"approvalReason":"example-approvalreason"}}},"description":"`approvalReason` is required and capped at 1000 characters. Keep the reason operational and sanitized. Current service evidence applies Medically Unlikely Edit (MUE) quantity reductions and records snapshots for rollback."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/auto-fixes/{autoFixRunId}/revert":{"post":{"operationId":"revertPreventionAutoFix","summary":"Revert a prevention auto-fix","description":"Reverts a prior applied auto-fix run when it belongs to the organization and contains reversible rollback data.\n\n### When to use\nUse this endpoint when a previously applied deterministic prevention fix should be undone before submission.\n\n### Before calling\nAuthenticate with Prevention write scope and use an `autoFixRunId` for an applied run in the same organization.\n\n### Request guidance\n`revertReason` is required and capped at 1000 characters. Current service evidence reverts supported quantity snapshots on claim lines.\n\n### Request notes\n- `revertReason` is required.\n- Only applied runs with supported rollback data can be reverted.\n\n### Response semantics\nHTTP 200 returns `status: REVERTED` and the updated auto-fix run in the generic workflow envelope. It is a local claim-line rollback, not a payer or clearinghouse transaction.\n\n### Response notes\n- `status` is `REVERTED` on success.\n- The updated run records who reverted it and why in current handler behavior.\n\n### Errors and retries\n400 can mean rollback data is missing. 404 can mean the applied run or claim line was not found for the organization. Re-read the run before retrying after a timeout.\n\n### Error notes\n- 404 means no applied org-owned auto-fix run matched the path ID.\n- 400 means the stored snapshot is not reversible.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"autoFixRunId","in":"path","description":"QuickRCM prevention auto-fix run identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"revertReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Required sanitized explanation for reverting the local auto-fix."}},"required":["revertReason"]},"example":{"revertReason":"example-revertreason"}}},"description":"`revertReason` is required and capped at 1000 characters. Current service evidence reverts supported quantity snapshots on claim lines."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/predictions":{"post":{"operationId":"predictPreventionDenialRisk","summary":"Queue denial risk prediction","description":"Validates an organization-owned claim and either validates, simulates, or queues a local denial-risk prediction work item.\n\n### When to use\nUse this endpoint when an external workflow wants QuickRCM to prepare denial-risk prediction work for a claim without invoking live large language model (LLM) generation synchronously.\n\n### Before calling\nAuthenticate with Prevention write scope. Resolve the claim in QuickRCM first and decide safe mode.\n\n### Request guidance\n`claimId` is required in the body. Safe-mode precedence is `validateOnly`, then `dryRun`, otherwise queue mode. Queue mode creates or reuses a local `PENDING_PREDICTION` work item.\n\n### Request notes\n- `claimId` is required in the request body.\n- `idempotencyKey` is optional and capped at 200 characters.\n- `externalDispatch` remains false in the immediate public response.\n- Passthrough body properties are not documented public contract fields and must not carry PHI, raw claim payloads, raw EDI, vendor payloads, credentials, or tokens.\n\n### Response semantics\nHTTP 200 returns workflow state with `status`, `mode`, `claimId`, optional work item fields, and `externalDispatch: false`. It is not the final risk score or large language model (LLM) rationale.\n\n### Response notes\n- `workItemId` is present in queue mode when a work item is created or reused.\n- `mode` describes whether the call validated, dry-ran, or queued.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization claim. Retry queue-mode network failures with the same `idempotencyKey` only for the same prediction request.\n\n### Error notes\n- 404 means the claim could not be found in the API key organization.\n- Do not present this response as a denial probability result.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","default":true,"description":"Default true. Queues a local `PENDING_PREDICTION` work item when no higher-precedence flag is set."},"validateOnly":{"type":"boolean","default":false,"description":"Validates ownership and request shape without queueing."},"dryRun":{"type":"boolean","default":false,"description":"Simulates the request without queueing."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."},"claimId":{"type":"string","minLength":1,"description":"QuickRCM claim identifier in the body. The claim must belong to the authenticated organization."}},"required":["claimId"]},"example":{"claimId":"00000000-0000-4000-8000-000000000001","queueOnly":true,"validateOnly":false,"dryRun":false,"idempotencyKey":"example-idempotencykey"}}},"description":"`claimId` is required in the body. Safe-mode precedence is `validateOnly`, then `dryRun`, otherwise queue mode. Queue mode creates or reuses a local `PENDING_PREDICTION` work item."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/work-items/{workItemId}":{"get":{"operationId":"getPreventionWorkItem","summary":"Get prevention work item status","description":"Returns the status of a queued public prevention work item when it belongs to the authenticated organization. Metadata is not returned.","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"workItemId","in":"path"}],"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/predictions/{predictionId}/outcome":{"post":{"operationId":"recordPreventionPredictionOutcome","summary":"Record denial prediction outcome","description":"Records the actual outcome for an organization-owned denial prediction to support feedback and accuracy tracking.\n\n### When to use\nUse this after payer or internal claim outcome evidence is known and you want to close the loop on a prior prevention prediction.\n\n### Before calling\nAuthenticate with Prevention write scope. Use a `predictionId` from the same organization and determine the final outcome category.\n\n### Request guidance\n`actualOutcome` is required and must be `DENIED`, `PAID`, `PARTIAL`, or `PENDING`. Include `denialCategory` only when the outcome and evidence support it. `denialCaseId` is accepted by the public schema and echoed by current handler behavior, but implementation evidence does not show a same-org DenialCase lookup in this endpoint.\n\n### Request notes\n- `actualOutcome` is required.\n- `denialCategory` uses generated DenialCategory enum values.\n- Do not send raw remittance, EOB, or payer response payloads.\n\n### Response semantics\nHTTP 200 returns `status: UPDATED`, the updated prediction, and nullable `denialCaseId` in the generic workflow envelope. The handler records feedback and computes `wasAccurate` from risk level and outcome when not pending.\n\n### Response notes\n- `prediction` is a generic serialized local record.\n- `wasAccurate` can remain null when outcome is `PENDING`.\n\n### Errors and retries\n400 means invalid outcome or category. 404 means the prediction was not found in the authenticated organization. Re-read prediction state before retrying an ambiguous update.\n\n### Error notes\n- 404 means the prediction ID does not belong to the API key organization.\n- Do not retry invalid enum values unchanged.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"predictionId","in":"path","description":"QuickRCM denial prediction identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"actualOutcome":{"type":"string","enum":["DENIED","PAID","PARTIAL","PENDING"],"description":"Required outcome value: `DENIED`, `PAID`, `PARTIAL`, or `PENDING`."},"denialCaseId":{"type":"string","minLength":1,"description":"Optional denial case identifier accepted by the schema and echoed by current handler behavior; do not rely on this endpoint to validate or mutate the denial case."},"denialCategory":{"type":"string","enum":["ELIGIBILITY","AUTHORIZATION","CODING","MEDICAL_NECESSITY","TIMELY_FILING","COB","BENEFIT_EXHAUSTED","DUPLICATE","BUNDLING","OTHER"],"description":"Optional denial category enum when the actual outcome is tied to a known denial reason."}},"required":["actualOutcome"]},"example":{"actualOutcome":"DENIED","denialCaseId":"00000000-0000-4000-8000-000000000001","denialCategory":"ELIGIBILITY"}}},"description":"`actualOutcome` is required and must be `DENIED`, `PAID`, `PARTIAL`, or `PENDING`. Include `denialCategory` only when the outcome and evidence support it. `denialCaseId` is accepted by the public schema and echoed by current handler behavior, but implementation evidence does not show a same-org DenialCase lookup in this endpoint."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/rules":{"post":{"operationId":"createPreventionRule","summary":"Create a prevention rule","description":"Creates a local prevention rule draft for the authenticated organization.\n\n### When to use\nUse this endpoint when an integration wants to add a tenant-specific prevention rule that can warn on or block matching claim conditions after review.\n\n### Before calling\nAuthenticate with Prevention write scope. Define a rule name, action, and safe JSON conditions that match the organization policy.\n\n### Request guidance\n`name` and `action` are required. `action` must be `BLOCK_SUBMISSION` or `WARN_ONLY`. `conditions` defaults to an empty object and should use documented organization-local rule fields instead of raw payer payloads.\n\n### Request notes\n- `name` is capped at 255 characters.\n- `warningMessage` is capped at 2000 characters.\n- `changeReason` is capped at 1000 characters.\n\n### Response semantics\nHTTP 200 returns `status: CREATED` and a serialized local rule in the generic workflow envelope. Current handler creates version 1 and defaults lifecycle and approval statuses to draft values when omitted.\n\n### Response notes\n- `rule` is returned as a generic serialized local record.\n- Creation does not prove the rule is approved for enforcement.\n\n### Errors and retries\n400 means invalid rule shape. If a create request times out, list or inspect rules before retrying because the schema does not expose an idempotency key for rule creation.\n\n### Error notes\n- Do not retry a timed-out create blindly without checking for an existing rule.\n- 403 means Prevention write scope is missing.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable prevention rule name."},"action":{"type":"string","enum":["BLOCK_SUBMISSION","WARN_ONLY"],"description":"Required rule action: `BLOCK_SUBMISSION` or `WARN_ONLY`."},"conditions":{"type":"object","additionalProperties":{},"default":{},"description":"JSON object describing the rule match criteria. Keep vendor payloads and protected health information (PHI) out of this object."},"warningMessage":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional message shown when the rule warns or blocks."},"lifecycleStatus":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local lifecycle label; current handler defaults to `DRAFT` when omitted."},"approvalStatus":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local approval label; current handler defaults to `DRAFT` when omitted."},"changeReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional audit explanation for why the rule draft is being created, capped at 1000 characters."}},"required":["name","action"]},"example":{"name":"Example prevention_rule","action":"BLOCK_SUBMISSION","conditions":{},"warningMessage":"example-warningmessage","lifecycleStatus":"example-lifecyclestatus","approvalStatus":"example-approvalstatus","changeReason":"example-changereason"}}},"description":"`name` and `action` are required. `action` must be `BLOCK_SUBMISSION` or `WARN_ONLY`. `conditions` defaults to an empty object and should use documented organization-local rule fields instead of raw payer payloads."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/rules/{ruleId}":{"put":{"operationId":"updatePreventionRule","summary":"Update a prevention rule","description":"Updates an organization-owned prevention rule and records a new version snapshot in current handler behavior.\n\n### When to use\nUse this endpoint to revise rule conditions, warning text, action, lifecycle metadata, or activation state before approval or enforcement.\n\n### Before calling\nAuthenticate with Prevention write scope and load the current rule from the same organization.\n\n### Request guidance\nSend only fields that should change. `action`, when supplied, must be `BLOCK_SUBMISSION` or `WARN_ONLY`. Keep `conditions` JSON structured and sanitized.\n\n### Request notes\n- `isActive` can be used to activate or deactivate a rule.\n- `conditions` replaces the supplied JSON object when present.\n- Use `changeReason` for audit-friendly change context.\n\n### Response semantics\nHTTP 200 returns `status: UPDATED` and the updated serialized rule. Current handler increments `currentVersion` and creates a version snapshot.\n\n### Response notes\n- `status` is `UPDATED` on success.\n- `rule` is a generic serialized local record.\n\n### Errors and retries\n400 means invalid patch fields. 404 means the rule does not exist in the organization. Re-read the rule before retrying after an ambiguous timeout to avoid overwriting newer changes.\n\n### Error notes\n- 404 means the rule was not found for the organization.\n- Do not retry stale updates without reloading current rule state.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ruleId","in":"path","description":"QuickRCM prevention rule identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional replacement human-readable rule name, capped at 255 characters."},"action":{"type":"string","enum":["BLOCK_SUBMISSION","WARN_ONLY"],"description":"Optional replacement rule action: `BLOCK_SUBMISSION` or `WARN_ONLY`."},"conditions":{"type":"object","additionalProperties":{},"default":{},"description":"Optional replacement JSON object for match criteria. When supplied, it replaces the prior conditions object."},"warningMessage":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional replacement warning or blocking message, capped at 2000 characters."},"lifecycleStatus":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local lifecycle label to store on the rule."},"approvalStatus":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local approval label to store on the rule."},"changeReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional audit explanation for the rule update."},"isActive":{"type":"boolean","description":"Optional boolean to enable or disable the local rule."}}},"example":{"name":"Example prevention_rule","action":"BLOCK_SUBMISSION","conditions":{},"warningMessage":"example-warningmessage","lifecycleStatus":"example-lifecyclestatus","approvalStatus":"example-approvalstatus","changeReason":"example-changereason","isActive":true}}},"description":"Send only fields that should change. `action`, when supplied, must be `BLOCK_SUBMISSION` or `WARN_ONLY`. Keep `conditions` JSON structured and sanitized."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/rules/{ruleId}/approve":{"post":{"operationId":"approvePreventionRule","summary":"Approve a prevention rule","description":"Approves an organization-owned prevention rule and sets its lifecycle target to `PILOT` or `ENFORCE`.\n\n### When to use\nUse this after a reviewer has validated a rule and wants it to progress out of draft workflow.\n\n### Before calling\nAuthenticate with Prevention write scope. Confirm the rule belongs to the organization and has completed any required simulation, especially for promoted learned rules moving to enforcement.\n\n### Request guidance\n`lifecycleStatus` defaults to `ENFORCE` and must be either `PILOT` or `ENFORCE`. Include `changeReason` for audit context.\n\n### Request notes\n- `lifecycleStatus` defaults to `ENFORCE`.\n- `changeReason` is optional and capped at 1000 characters.\n\n### Response semantics\nHTTP 200 returns `status: APPROVED` and the updated serialized rule. Current handler marks approval status approved, records approver metadata, and snapshots the next version.\n\n### Response notes\n- `status` is `APPROVED` on success.\n- Approval is local QuickRCM rule lifecycle state.\n\n### Errors and retries\n400 can occur when enforcement approval requires a prior simulation. 404 means the rule was not found in the organization. Re-read rule approval state before retrying after a timeout.\n\n### Error notes\n- 400 can mean simulation is required before enforcement.\n- 404 means the rule was not found for the API key organization.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ruleId","in":"path","description":"QuickRCM prevention rule identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lifecycleStatus":{"type":"string","enum":["PILOT","ENFORCE"],"default":"ENFORCE","description":"Approval target lifecycle: `PILOT` or `ENFORCE`. Defaults to `ENFORCE`."},"changeReason":{"type":"string","minLength":1,"maxLength":1000,"description":"Optional approval explanation for audit history."}}},"example":{"lifecycleStatus":"ENFORCE","changeReason":"example-changereason"}}},"description":"`lifecycleStatus` defaults to `ENFORCE` and must be either `PILOT` or `ENFORCE`. Include `changeReason` for audit context."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/rules/{ruleId}/simulate":{"post":{"operationId":"simulatePreventionRule","summary":"Simulate a prevention rule","description":"Runs a local simulation for an organization-owned prevention rule over a bounded historical claim sample without changing production claim state.\n\n### When to use\nUse this before approving or enforcing a rule, or to estimate rule hit counts and held amount under proposed conditions.\n\n### Before calling\nAuthenticate with Prevention write scope. Confirm the rule belongs to the organization and choose a `sampleWindowDays` between 1 and 365.\n\n### Request guidance\nOmit `rule` to simulate the stored rule, or provide an inline rule snapshot with required `action` to test proposed changes. Current handler samples up to 1000 organization-owned claims in the time window.\n\n### Request notes\n- `sampleWindowDays` defaults to 90 and must be 1 through 365.\n- Inline `rule.action` is required when `rule` is supplied.\n- Current matching evidence includes conditions such as `payerConfigId` and `minAmount`.\n\n### Response semantics\nHTTP 200 returns `status: SIMULATED` and a `simulation` object with sampled claim count, hit count, blocked or warning counts, amount held, and up to 25 sample claim summaries. It does not mutate claims or approve the rule.\n\n### Response notes\n- `sampledClaims` is capped by current handler query behavior.\n- `sampleClaims` contains claim IDs and totals only in current handler behavior.\n\n### Errors and retries\n400 means invalid window or rule snapshot. 404 means the stored rule was not found. Simulations are safe to retry, but repeated runs may create multiple local simulation records.\n\n### Error notes\n- 404 means the rule was not found for the organization.\n- Do not treat simulation results as approval.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ruleId","in":"path","description":"QuickRCM prevention rule identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sampleWindowDays":{"type":"integer","minimum":1,"maximum":365,"default":90,"description":"Number of days of recent claims to sample. Defaults to 90; valid range is 1 through 365."},"rule":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for the queue, template, person, payer, or workflow object."},"action":{"type":"string","enum":["BLOCK_SUBMISSION","WARN_ONLY"]},"conditions":{"type":"object","additionalProperties":{},"default":{},"description":"Structured routing-rule matching criteria for Denial Management queues. Use documented child fields and avoid opaque PHI-heavy values."},"warningMessage":{"type":"string","minLength":1,"maxLength":2000,"description":"Message shown or stored for a warning-style prevention rule."}},"required":["action"],"description":"Optional inline rule snapshot for simulation without updating the stored rule."}}},"example":{"sampleWindowDays":90,"rule":{"action":"BLOCK_SUBMISSION","name":"Example simulate_prevention_rule","conditions":{},"warningMessage":"example-warningmessage"}}}},"description":"Omit `rule` to simulate the stored rule, or provide an inline rule snapshot with required `action` to test proposed changes. Current handler samples up to 1000 organization-owned claims in the time window."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/alerts/{alertId}/act":{"post":{"operationId":"actOnPreventionAlert","summary":"Record action on a prevention alert","description":"Records that an organization-owned prevention alert was acted upon and stores a required action note.\n\n### When to use\nUse this endpoint when a user or automation completed the recommended prevention action and wants to close the alert loop with an audit-friendly note.\n\n### Before calling\nAuthenticate with Prevention write scope and verify that the alert still belongs to the same organization.\n\n### Request guidance\nSend `actionTaken` with the completed action. Optionally send `resolutionCode`; current handler defaults it to `ACTION_TAKEN` and sets both `acknowledgedAt` when absent and `resolvedAt`. Keep notes concise and do not include raw payer payloads, patient demographics, credentials, or claim attachments.\n\n### Request notes\n- `actionTaken` is required and capped at 1000 characters.\n- `resolutionCode` is optional, capped at 100 characters, and defaults to `ACTION_TAKEN` when omitted.\n\n### Response semantics\nHTTP 200 returns the generic Prevention workflow envelope with `status: UPDATED` and an updated alert in `data.alert` when using the current handler. The generated OpenAPI schema leaves `data` open-ended.\n\n### Response notes\n- The workflow response includes `meta.organizationId`.\n- The action is local alert workflow state only.\n- Current handler marks the returned alert as resolved by setting `resolvedAt`.\n\n### Errors and retries\nA missing or blank `actionTaken` is a 400 validation failure. Treat 404 as missing or wrong-organization alert. Re-read the alert before retrying after an ambiguous timeout.\n\n### Error notes\n- 400 means the action note failed validation.\n- 403 means Prevention write scope is missing.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"alertId","in":"path","description":"QuickRCM prevention alert identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"actionTaken":{"type":"string","minLength":1,"maxLength":1000,"description":"Required description of the completed prevention action."},"resolutionCode":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local workflow code for the completed action. Defaults to `ACTION_TAKEN` when omitted."}},"required":["actionTaken"]},"example":{"actionTaken":"example-actiontaken","resolutionCode":"example-resolutioncode"}}},"description":"Send `actionTaken` with the completed action. Optionally send `resolutionCode`; current handler defaults it to `ACTION_TAKEN` and sets both `acknowledgedAt` when absent and `resolvedAt`. Keep notes concise and do not include raw payer payloads, patient demographics, credentials, or claim attachments."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/alerts/{alertId}/dismiss":{"post":{"operationId":"dismissPreventionAlert","summary":"Dismiss a prevention alert","description":"Dismisses an organization-owned prevention alert with a required reason.\n\n### When to use\nUse this when the alert is no longer actionable, is a false positive, or was handled through another workflow and should leave the active queue.\n\n### Before calling\nAuthenticate with Prevention write scope and confirm the alert is in the authenticated organization.\n\n### Request guidance\nSend a concise `reason` up to 1000 characters. Optionally send `resolutionCode`; current handler defaults it to `DISMISSED`. Do not use dismissal notes for raw payer responses, credentials, or detailed patient narratives.\n\n### Request notes\n- `reason` is required and capped at 1000 characters.\n- `resolutionCode` is optional, capped at 100 characters, and defaults to `DISMISSED` when omitted.\n\n### Response semantics\nHTTP 200 returns the generic workflow envelope with dismissal status and updated alert data in current handler behavior. The dismissal is local and does not alter the underlying claim submission state by itself.\n\n### Response notes\n- Current handler returns `status: DISMISSED` in `data`.\n- The returned alert includes `dismissedAt` and `resolutionCode` when serialized.\n- `meta.organizationId` confirms the API key organization.\n\n### Errors and retries\nFix missing `reason` errors before retrying. Treat 404 as an alert ownership or existence failure. Back off on 429.\n\n### Error notes\n- 400 means the dismissal reason is absent or invalid.\n- 404 means the alert was not found for the organization.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"alertId","in":"path","description":"QuickRCM prevention alert identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":1000,"description":"Required dismissal rationale. Keep it concise and sanitized."},"resolutionCode":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local workflow code for the dismissal. Defaults to `DISMISSED` when omitted."}},"required":["reason"]},"example":{"reason":"example-reason","resolutionCode":"example-resolutioncode"}}},"description":"Send a concise `reason` up to 1000 characters. Optionally send `resolutionCode`; current handler defaults it to `DISMISSED`. Do not use dismissal notes for raw payer responses, credentials, or detailed patient narratives."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/education":{"post":{"operationId":"createPreventionEducationContent","summary":"Create provider education content","description":"Creates provider education content for the authenticated organization without invoking external generation.\n\n### When to use\nUse this endpoint to assign or store prevention education content for a provider, physician, or organization member after a denial pattern or scorecard review.\n\n### Before calling\nAuthenticate with Prevention write scope. Verify `providerId` is a valid Provider, OrganizationPhysician, or active OrganizationMember user in the organization. Verify optional `payerId` as an organization-owned payer config.\n\n### Request guidance\n`providerId`, `topic`, `description`, and `educationType` are required. Use `educationContent`, `actionItems`, and `resourceUrls` for sanitized educational material only.\n\n### Request notes\n- `severity` defaults to `MEDIUM` and allows `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.\n- `educationContent` is capped at 20000 characters.\n- `resourceUrls` must contain valid URLs.\n\n### Response semantics\nHTTP 200 returns `status: CREATED` and a serialized local education item. The current handler sets status to `ASSIGNED` and assigns the item from the public API actor.\n\n### Response notes\n- `education` is a generic serialized ProviderEducationItem record.\n- Creation does not deliver email, learning management system (LMS) content, or payer communication.\n\n### Errors and retries\n400 means invalid body shape or URL. 404 means provider or payer context was not found in the organization. If creation times out, check for duplicate education before retrying because no idempotency key is exposed.\n\n### Error notes\n- 404 can mean provider identity or optional payer was not found in the organization.\n- Do not retry duplicate-prone creates blindly after a timeout.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"type":"string","minLength":1,"description":"Identifier for a provider, organization physician, or active organization member user in the authenticated organization."},"topic":{"type":"string","minLength":1,"maxLength":255,"description":"Provider education topic, capped at 255 characters."},"description":{"type":"string","minLength":1,"maxLength":2000,"description":"Short description of the education item, capped at 2000 characters."},"educationType":{"type":"string","minLength":1,"maxLength":100,"description":"Organization-local education type label."},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"],"default":"MEDIUM","description":"Optional education severity from `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`; defaults to `MEDIUM`."},"category":{"type":"string","minLength":1,"maxLength":100,"description":"Optional denial or prevention category stored as trigger pattern context."},"reasonCode":{"type":"string","minLength":1,"maxLength":100,"description":"Optional denial root-cause or reason code accepted by the request schema. Current create handler does not persist a separate reason-code field."},"payerId":{"type":"string","minLength":1,"description":"Optional payer configuration identifier. When supplied, the payer must belong to the authenticated organization."},"educationContent":{"type":"string","minLength":1,"maxLength":20000,"description":"Optional sanitized education body, capped at 20000 characters."},"actionItems":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"Optional array of structured action items. Do not include protected health information (PHI) or secrets."},"resourceUrls":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Optional array of valid URLs for safe education resources."}},"required":["providerId","topic","description","educationType"]},"example":{"providerId":"00000000-0000-4000-8000-000000000001","topic":"example-topic","description":"Example prevention_education_content note","educationType":"example-educationtype","severity":"MEDIUM","category":"example-category","reasonCode":"example-reasoncode","payerId":"87726","educationContent":"example-educationcontent","actionItems":[{}],"resourceUrls":[]}}},"description":"`providerId`, `topic`, `description`, and `educationType` are required. Use `educationContent`, `actionItems`, and `resourceUrls` for sanitized educational material only."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/education/{educationContentId}":{"put":{"operationId":"updatePreventionEducationContent","summary":"Update provider education content","description":"Updates organization-owned provider education content and local workflow metadata.\n\n### When to use\nUse this endpoint to revise education copy, status, severity, provider assignment, resources, or action items.\n\n### Before calling\nAuthenticate with Prevention write scope and load the education content from the same organization. If changing `providerId`, ensure the new identity belongs to the organization.\n\n### Request guidance\nSend only fields that should change. `status`, when supplied, is a free-form string in the generated schema; current handler uses status values such as `VIEWED`, `ACKNOWLEDGED`, and `COMPLETED` to set timestamps.\n\n### Request notes\n- All create fields are optional on update.\n- `resourceUrls` entries must remain valid URLs.\n- Avoid placing patient details in education content or action items.\n\n### Response semantics\nHTTP 200 returns `status: UPDATED` and a serialized local education item. Updating content is local workflow state and does not imply delivery.\n\n### Response notes\n- `education` is a generic serialized local record.\n- Status timestamps may be updated by current handler behavior for certain statuses.\n\n### Errors and retries\n400 means invalid body shape or URL. 404 means the education record or replacement provider was not found in the organization. Re-read before retrying stale updates.\n\n### Error notes\n- 404 means the education content or provider identity was not found in the organization.\n- Do not retry stale updates without reloading current content.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"educationContentId","in":"path","description":"QuickRCM provider education content identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"type":"string","minLength":1,"description":"Optional replacement provider, organization physician, or active organization member user identifier; it must resolve in the authenticated organization."},"topic":{"type":"string","minLength":1,"maxLength":255,"description":"Optional replacement education topic, capped at 255 characters."},"description":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional replacement description, capped at 2000 characters."},"educationType":{"type":"string","minLength":1,"maxLength":100,"description":"Optional replacement organization-local education type label."},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"],"default":"MEDIUM","description":"Optional replacement severity from `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`."},"category":{"type":"string","minLength":1,"maxLength":100,"description":"Optional replacement trigger pattern category stored on the education item."},"reasonCode":{"type":"string","minLength":1,"maxLength":100,"description":"Optional request-schema field accepted on update. Current handler does not map it to a separate persisted field."},"payerId":{"type":"string","minLength":1,"description":"Optional request-schema field accepted on update. Current handler does not re-check or map it during update."},"educationContent":{"type":"string","minLength":1,"maxLength":20000,"description":"Optional replacement sanitized education body, capped at 20000 characters."},"actionItems":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"Optional replacement array of structured action items."},"resourceUrls":{"type":"array","items":{"type":"string","format":"uri"},"default":[],"description":"Replacement list of valid education resource URLs when supplied."},"status":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local education workflow status. Current handler maps `VIEWED`, `ACKNOWLEDGED`, and `COMPLETED` to timestamps."}}},"example":{"providerId":"00000000-0000-4000-8000-000000000001","topic":"example-topic","description":"Example prevention_education_content note","educationType":"example-educationtype","severity":"MEDIUM","category":"example-category","reasonCode":"example-reasoncode","payerId":"87726"}}},"description":"Send only fields that should change. `status`, when supplied, is a free-form string in the generated schema; current handler uses status values such as `VIEWED`, `ACKNOWLEDGED`, and `COMPLETED` to set timestamps."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/education/{educationContentId}/delivery":{"post":{"operationId":"recordPreventionEducationDelivery","summary":"Record provider education delivery","description":"Records local delivery or engagement status for organization-owned provider education content.\n\n### When to use\nUse this endpoint when a provider has been assigned, viewed, acknowledged, or completed education content and QuickRCM should track the state.\n\n### Before calling\nAuthenticate with Prevention write scope and use an education content ID from the same organization.\n\n### Request guidance\n`deliveryMethod` is required and must be `VIEWED`, `COMPLETED`, `ASSIGNED`, or `ACKNOWLEDGED`. `timeSpent` is optional seconds from 0 through 86400.\n\n### Request notes\n- `deliveryMethod` is required.\n- `timeSpent` is optional and capped at 86400 seconds.\n- Do not include transcript or protected health information (PHI) in this request.\n\n### Response semantics\nHTTP 200 returns `status: UPDATED`, the updated education record, and nullable `timeSpent` in the generic workflow envelope. It records local workflow state and does not send content externally.\n\n### Response notes\n- Current handler updates education status to the delivery method.\n- Certain delivery methods set viewed, acknowledged, or completed timestamps when not already present.\n\n### Errors and retries\n400 means invalid delivery enum or time spent. 404 means the education content was not found for the organization.\n\n### Error notes\n- 404 means the education content ID is missing or wrong-tenant.\n- Do not retry invalid enum values unchanged.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"educationContentId","in":"path","description":"QuickRCM provider education content identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deliveryMethod":{"type":"string","enum":["VIEWED","COMPLETED","ASSIGNED","ACKNOWLEDGED"],"description":"Required delivery or engagement state: `VIEWED`, `COMPLETED`, `ASSIGNED`, or `ACKNOWLEDGED`."},"timeSpent":{"type":["integer","null"],"minimum":0,"maximum":86400,"description":"Optional engagement duration in seconds, from 0 through 86400."}},"required":["deliveryMethod"]},"example":{"deliveryMethod":"VIEWED","timeSpent":1}}},"description":"`deliveryMethod` is required and must be `VIEWED`, `COMPLETED`, `ASSIGNED`, or `ACKNOWLEDGED`. `timeSpent` is optional seconds from 0 through 86400."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/education/generate":{"post":{"operationId":"generatePreventionEducation","summary":"Queue provider education generation","description":"Validates provider and denial-pattern inputs, analyzes a bounded set of matching local denial cases, and returns safe workflow state without invoking a large language model (LLM) in the public handler.\n\n### When to use\nUse this endpoint to validate or queue-like simulate education generation inputs before separately creating reviewed provider education content.\n\n### Before calling\nAuthenticate with Prevention write scope. Verify `providerId` belongs to the organization and choose a denial `category` with optional reason, payer, and education type.\n\n### Request guidance\n`providerId` and `category` are required. Safe-mode precedence is `validateOnly`, then `dryRun`, otherwise `queueOnly`, but current handler evidence does not create work items for this endpoint; it returns validated or queued-style workflow state with `externalDispatch: false`.\n\n### Request notes\n- `category` is required and capped at 100 characters.\n- `reasonCode` and `educationType` are optional strings capped at 100 characters.\n- `idempotencyKey` is accepted by the schema, but current handler evidence does not show durable queue creation for this endpoint.\n- Passthrough body properties are not documented public contract fields and must not carry PHI, raw claim payloads, raw EDI, vendor payloads, credentials, or tokens.\n\n### Response semantics\nHTTP 200 returns status, mode, provider/category context, number of analyzed denial cases, optional idempotency key, and `externalDispatch: false`. It is not generated education content and not live large language model (LLM) output.\n\n### Response notes\n- `analyzedDenialCases` is the count of matching local denial cases inspected by current handler behavior.\n- `externalDispatch` is false.\n- Use create/update education endpoints for reviewed content.\n\n### Errors and retries\n400 means invalid request fields. 404 can mean provider identity was not found. Back off on 429.\n\n### Error notes\n- 404 can mean provider identity was not found in the organization.\n- Do not present the response as AI-generated education material.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"type":"string","minLength":1,"description":"Provider, organization physician, or active member user identifier in the authenticated organization."},"category":{"type":"string","minLength":1,"maxLength":100,"description":"Denial or prevention category used to find local context for education generation validation."},"reasonCode":{"type":"string","minLength":1,"maxLength":100,"description":"Optional denial root-cause or reason code filter."},"payerId":{"type":"string","minLength":1,"description":"Optional payer configuration identifier used to filter matching denial cases."},"educationType":{"type":"string","minLength":1,"maxLength":100,"description":"Optional provider education format or workflow type capped at 100 characters."},"queueOnly":{"type":"boolean","default":true,"description":"Default true safe-workflow flag. Current public handler evidence validates and returns local workflow state rather than dispatching external generation."},"validateOnly":{"type":"boolean","default":false,"description":"Highest-precedence safety flag. Validates provider, category, payer, and denial-pattern context without external generation."},"dryRun":{"type":"boolean","default":false,"description":"Second-precedence safety flag. Simulates education generation request handling without external generation."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional schema-accepted retry key capped at 200 characters. Current handler evidence does not show durable queue replay for this endpoint."}},"required":["providerId","category"]},"example":{"providerId":"00000000-0000-4000-8000-000000000001","category":"example-category","reasonCode":"example-reasoncode","payerId":"87726","educationType":"example-educationtype","queueOnly":true,"validateOnly":false,"dryRun":false,"idempotencyKey":"example-idempotencykey"}}},"description":"`providerId` and `category` are required. Safe-mode precedence is `validateOnly`, then `dryRun`, otherwise `queueOnly`, but current handler evidence does not create work items for this endpoint; it returns validated or queued-style workflow state with `externalDispatch: false`."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prevention/learned-rules/{learnedRuleId}/promote":{"post":{"operationId":"promotePreventionLearnedRule","summary":"Promote a learned payer rule","description":"Promotes an organization-owned learned payer rule into a draft local prevention rule workflow.\n\n### When to use\nUse this after a payer denial profile has identified a learned rule that should be reviewed and managed as a tenant-specific prevention rule.\n\n### Before calling\nAuthenticate with Prevention write scope. Use a valid learned rule identifier from the organization. Current handler expects IDs shaped like `learned-{profileId}-{index}` for direct profile lookup.\n\n### Request guidance\n`ruleName` and `action` are required. Provide `warningMessage` when the learned rule's suggested action should be overridden.\n\n### Request notes\n- `ruleName` is capped at 255 characters.\n- `action` must be `BLOCK_SUBMISSION` or `WARN_ONLY`.\n- `warningMessage` is optional and capped at 2000 characters.\n\n### Response semantics\nHTTP 200 returns `status: CREATED` and the new serialized rule. Current handler creates a draft rule with `approvalStatus: PENDING_APPROVAL`, conditions derived from the learned rule, and a version snapshot.\n\n### Response notes\n- The created rule still requires review and approval before enforcement.\n- Promotion is local; it does not update payer systems.\n\n### Errors and retries\n404 means the learned payer rule or profile was not found for the organization. If the promote call times out, check for the created rule before retrying because the schema has no idempotency key.\n\n### Error notes\n- 404 means no matching learned rule was found in the authenticated organization.\n- Do not retry blindly after ambiguous create timeouts.\n","tags":["Prevention"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"learnedRuleId","in":"path","description":"Learned payer rule identifier in the path. Current handler recognizes `learned-{profileId}-{index}` for direct profile lookup."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ruleName":{"type":"string","minLength":1,"maxLength":255,"description":"Name for the promoted local prevention rule."},"action":{"type":"string","enum":["BLOCK_SUBMISSION","WARN_ONLY"],"description":"Action for the promoted rule: `BLOCK_SUBMISSION` or `WARN_ONLY`."},"warningMessage":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional warning message to use instead of the learned rule suggested action."}},"required":["ruleName","action"]},"example":{"ruleName":"Example promote_prevention_learned_rule","action":"BLOCK_SUBMISSION","warningMessage":"example-warningmessage"}}},"description":"`ruleName` and `action` are required. Provide `warningMessage` when the learned rule's suggested action should be overridden."},"responses":{"200":{"description":"Prevention workflow result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Prevention workflow accepted for async processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied or missing scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prevention resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/requirements/check":{"post":{"operationId":"checkPriorAuthRequired","summary":"Check prior authorization requirement","description":"Checks whether a service appears to require prior authorization for the organization selected by the bearer API key, using payer, service, diagnosis, and optional provider/member/place-of-service context.\n\n### When to use\nUse this before creating a prior authorization case when an integration needs decision support for a planned service code and diagnosis code.\n\n### Before calling\nAuthenticate with a public API key that can access Prior Authorization. Prepare `payerId`, `serviceCode`, and `diagnosisCode`; include `providerNPI`, `memberId`, and place-of-service fields only when they are needed for the payer rule lookup.\n\n### Request guidance\n`payerId`, `serviceCode`, and `diagnosisCode` are required strings. Optional `providerNPI`, `memberId`, `placeOfService`, and `placeOfServiceCode` are bounded strings. The API key selects the organization; do not send an `organizationId` selector.\n\n### Request notes\n- Use a valid provider NPI only when payer logic requires provider identity.\n- `memberId` can identify a patient or subscriber and should not be logged raw.\n- `placeOfServiceCode` is limited to 10 characters by the public schema.\n\n### Response semantics\nHTTP 200 returns `requiresAuth` plus optional `policyInfo`, `requirements`, `evidenceSufficiency`, and `alternatives`, with `meta.organizationId`. This is requirement decision support only; it does not create a case, reserve an authorization number, or prove payer approval.\n\n### Response notes\n- `requiresAuth` is the primary result field.\n- `requirements` and `alternatives` are structured guidance, not authorization determinations.\n- The response has no priorAuthId because no case is created.\n\n### Errors and retries\nTreat 400 as invalid or incomplete request fields, 401 as missing or invalid credentials, 403 as a tenant or permission failure, 429 as a backoff signal, and 500 as transient only when retry limits allow.\n\n### Error notes\n- 400 can indicate missing required payer, service, or diagnosis context.\n- 429 should be retried with scheduled or exponential backoff.\n- 401 and 403 require credential, scope, or tenant-context correction before retrying.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payerId":{"type":"string","minLength":1,"maxLength":120,"description":"Required payer identifier used for prior authorization requirement lookup. Treat payer/member combinations as sensitive workflow context."},"providerNPI":{"type":"string","minLength":1,"maxLength":20,"description":"Optional National Provider Identifier for the ordering or rendering provider when payer rules need provider context."},"serviceCode":{"type":"string","minLength":1,"maxLength":40,"description":"Required service or procedure code being checked for prior authorization requirements."},"diagnosisCode":{"type":"string","minLength":1,"maxLength":40,"description":"Required diagnosis code used with the service code to evaluate authorization requirements."},"memberId":{"type":"string","minLength":1,"maxLength":120,"description":"Optional payer member or subscriber identifier. Treat as PHI-adjacent and avoid logging raw values."},"placeOfService":{"type":"string","minLength":1,"maxLength":120,"description":"Optional human-readable place-of-service context."},"placeOfServiceCode":{"type":"string","minLength":1,"maxLength":10,"description":"Optional place-of-service code, capped at 10 characters."}},"required":["payerId","serviceCode","diagnosisCode"]},"example":{"payerId":"87726","serviceCode":"example-servicecode","diagnosisCode":"example-diagnosiscode","providerNPI":"1234567893","memberId":"W123456789","placeOfService":"example-placeofservice","placeOfServiceCode":"example-placeofservicecode"}}},"description":"`payerId`, `serviceCode`, and `diagnosisCode` are required strings. Optional `providerNPI`, `memberId`, `placeOfService`, and `placeOfServiceCode` are bounded strings. The API key selects the organization; do not send an `organizationId` selector."},"responses":{"200":{"description":"Prior authorization requirement result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"requiresAuth":{"type":"boolean"},"policyInfo":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}}},"requirements":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name","description"]}},"evidenceSufficiency":{"type":"object","additionalProperties":{}},"alternatives":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":"string"}},"required":["code","description"]}}},"required":["requiresAuth"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"requiresAuth":true,"policyInfo":{"name":"Example prior_auth_required","description":"Example prior_auth_required note"},"requirements":[{"name":"Example prior_auth_required","description":"Example prior_auth_required note"}],"evidenceSufficiency":{},"alternatives":[{"code":"ERROR","description":"Example prior_auth_required note"}]},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations":{"post":{"operationId":"createPriorAuth","summary":"Create prior authorization","description":"Creates a prior authorization case for the authenticated organization and returns a sanitized case summary.\n\n### When to use\nUse this when a requirement check, scheduling workflow, or clinical intake process has enough patient, service, diagnosis, and ordering-provider context to open a prior authorization case in QuickRCM.\n\n### Before calling\nCollect the required patient name, date of birth, service type, specific service, CPT code, diagnosis code, ordering physician, and payer context. Provide either `payerId` or `payerName`; include `payerName` when the payer ID may not resolve through QuickRCM payer lookup. Resolve optional appointment, member, place-of-service, requirement-check, and clinical evidence fields before sending the request.\n\n### Request guidance\nRequired fields are `patientFirstName`, `patientLastName`, `patientDOB`, `serviceType`, `specificService`, `cptCode`, `diagnosisCode`, and `orderingPhysician`, plus the cross-field payer rule that either `payerId` or `payerName` must be provided. Although the generated OpenAPI schema marks `payerId` and `payerName` individually optional, omitting both fails validation. Clinical/service fields include service type, service description, CPT/procedure code, diagnosis code, optional diagnosis description, clinical indication, and optional requirement evidence. Payer/member fields include payer id/name, member id, and place-of-service values. Workflow/integration fields include urgency, requirement-check carryover fields, and metadata. The API key selects the organization; do not send an `organizationId` selector.\n\n### Request notes\n- `serviceType` accepts the enum values exposed by the OpenAPI schema, including broad categories and more specific lower-case service families.\n- Patient name, DOB, MRN, member ID, and clinical indication are PHI or PHI-adjacent; examples must be synthetic.\n- `isAuthRequired*` fields can carry requirement-check evidence into the created case, but they should not contain raw vendor payloads.\n- `metadata` is for integration metadata only; do not store credentials, tokens, raw EDI, upload URLs, or vendor payloads there.\n- Provide `payerName` when using a `payerId` that may not resolve through QuickRCM payer lookup; the handler can return 400 asking for `payerName` explicitly.\n\n### Response semantics\nHTTP 201 returns `data.priorAuth` with local QuickRCM identifiers, status, service and diagnosis fields, payer/member fields when present, authorization-number fields when present, lifecycle timestamps, and `meta.organizationId`. It is a local case creation response, not payer approval, denial, or portal receipt.\n\n### Response notes\n- `authorizationNumber` can be null on case creation.\n- `submittedAt`, `approvedAt`, `deniedAt`, and `expirationDate` can be null depending on lifecycle state.\n- `organizationId` is returned in the resource and metadata but is not a public request selector.\n\n### Errors and retries\nTreat 400 as request validation failure, 402 as insufficient credits for the workflow, 401/403 as credential or tenant authorization failures, 429 as a backoff signal, and 500 as transient only with bounded retries. After a timeout, search by local workflow context before creating another case if duplicates would be harmful.\n\n### Error notes\n- 402 is explicitly declared for insufficient credits.\n- 400 can include missing required fields or invalid service type.\n- Do not treat a 201 response as payer acceptance.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientFirstName":{"type":"string","minLength":1,"maxLength":100,"description":"Required patient first name for the prior authorization case. Use synthetic values in public examples."},"patientLastName":{"type":"string","minLength":1,"maxLength":100,"description":"Required patient last name for the prior authorization case. Use synthetic values in public examples."},"patientDOB":{"type":"string","minLength":1,"description":"Required patient date of birth as YYYY-MM-DD or another ISO date string."},"mrn":{"type":"string","minLength":1,"maxLength":120,"description":"Optional medical record number. Treat as patient-identifying data."},"appointmentId":{"type":"string","minLength":1,"description":"Optional QuickRCM appointment identifier to link the prior authorization case to a scheduled encounter."},"serviceType":{"type":"string","enum":["IMAGING","SURGERY","THERAPY","DME","MEDICATION","imaging","surgery","therapy","dme","medication","imaging-xray","imaging-lab","imaging-mri","imaging-pet","surgery-oral","surgery-periodontal","surgery-anesthesia","surgery-assistance","therapy-radiation","therapy-inhalation","therapy-chemotherapy","therapy-dialysis","dme-purchased","dme-rental","dme-prosthetics","dme-hearing","dme-oxygen","medication-brand","medication-generic","medication-mail-order"],"description":"Required service category or detailed service family enum from the public schema."},"specificService":{"type":"string","minLength":1,"maxLength":250,"description":"Required human-readable service description, capped at 250 characters."},"cptCode":{"type":"string","minLength":1,"maxLength":40,"description":"Required CPT or procedure code for the requested service, capped at 40 characters."},"diagnosisCode":{"type":"string","minLength":1,"maxLength":40,"description":"Required diagnosis code supporting the requested service, capped at 40 characters."},"diagnosisDescription":{"type":"string","minLength":1,"maxLength":500,"description":"Optional human-readable diagnosis description, capped at 500 characters. Keep it clinically necessary and synthetic in examples."},"orderingPhysician":{"type":"string","minLength":1,"maxLength":200,"description":"Required ordering physician name or display label, capped at 200 characters. Treat as clinical workflow context."},"orderingPhysicianNPI":{"type":"string","minLength":1,"maxLength":20,"description":"Optional ordering physician National Provider Identifier, capped at 20 characters."},"clinicalIndication":{"type":"string","minLength":1,"maxLength":5000,"description":"Optional clinical rationale, capped at 5000 characters. Keep it clinically necessary and free of raw transcripts."},"payerId":{"type":"string","minLength":1,"maxLength":120,"description":"Conditionally required payer identifier associated with the authorization case when `payerName` is omitted, capped at 120 characters. If the ID may not resolve through QuickRCM payer lookup, also provide `payerName`."},"payerName":{"type":"string","minLength":1,"maxLength":200,"description":"Conditionally required payer display name when `payerId` is omitted or may not resolve, capped at 200 characters. Use synthetic payer names in examples."},"memberId":{"type":"string","minLength":1,"maxLength":120,"description":"Optional payer member or subscriber identifier, capped at 120 characters. Treat as PHI-adjacent."},"placeOfService":{"type":"string","minLength":1,"maxLength":120,"description":"Optional place-of-service label or description, capped at 120 characters."},"placeOfServiceCode":{"type":"string","minLength":1,"maxLength":10,"description":"Optional short place-of-service code, capped at 10 characters."},"urgency":{"type":"boolean","description":"Optional boolean indicating whether the case should be treated as urgent in local workflow state."},"isAuthRequiredResult":{"type":"boolean","description":"Optional copied boolean result from a prior-auth requirement check."},"isAuthRequiredPolicyName":{"type":"string","minLength":1,"maxLength":250,"description":"Optional policy name copied from a requirement check, capped at 250 characters."},"isAuthRequiredPolicyDescription":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional policy description copied from a requirement check, capped at 2000 characters."},"isAuthRequiredRequirements":{"description":"Optional structured requirements copied from a requirement check. Do not include raw payer payloads."},"isAuthRequiredEvidenceSufficiency":{"description":"Optional structured evidence-sufficiency object copied from a requirement check."},"requirements":{"description":"Optional structured case requirements object. Keep it sanitized and avoid raw vendor payloads."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional integration metadata object. Do not include credentials, tokens, raw EDI, upload URLs, or storage secrets."}},"required":["patientFirstName","patientLastName","patientDOB","serviceType","specificService","cptCode","diagnosisCode","orderingPhysician"]},"example":{"patientFirstName":"Example prior_auth","patientLastName":"Example prior_auth","patientDOB":"1984-03-22","serviceType":"IMAGING","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","orderingPhysician":"example-orderingphysician","mrn":"example-mrn","appointmentId":"00000000-0000-4000-8000-000000000001","diagnosisDescription":"Example prior_auth note","orderingPhysicianNPI":"1234567893","clinicalIndication":"example-clinicalindication","payerId":"87726","payerName":"Example prior_auth","memberId":"W123456789"}}},"description":"Required fields are `patientFirstName`, `patientLastName`, `patientDOB`, `serviceType`, `specificService`, `cptCode`, `diagnosisCode`, and `orderingPhysician`, plus the cross-field payer rule that either `payerId` or `payerName` must be provided. Although the generated OpenAPI schema marks `payerId` and `payerName` individually optional, omitting both fails validation. Clinical/service fields include service type, service description, CPT/procedure code, diagnosis code, optional diagnosis description, clinical indication, and optional requirement evidence. Payer/member fields include payer id/name, member id, and place-of-service values. Workflow/integration fields include urgency, requirement-check carryover fields, and metadata. The API key selects the organization; do not send an `organizationId` selector."},"responses":{"201":{"description":"Created prior authorization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"priorAuth":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"caseId":{"type":["string","null"]},"status":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"urgency":{"type":"boolean"},"serviceType":{"type":"string"},"specificService":{"type":"string"},"cptCode":{"type":"string"},"diagnosisCode":{"type":"string"},"diagnosisDescription":{"type":["string","null"]},"orderingPhysician":{"type":["string","null"]},"orderingPhysicianNPI":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"authorizationNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"deniedAt":{"type":["string","null"],"format":"date-time"},"denialReason":{"type":["string","null"]},"expirationDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","caseId","status","patientId","appointmentId","urgency","serviceType","specificService","cptCode","diagnosisCode","diagnosisDescription","orderingPhysician","orderingPhysicianNPI","payerId","payerName","memberId","authorizationNumber","submittedAt","approvedAt","deniedAt","denialReason","expirationDate","createdAt","updatedAt"]}},"required":["priorAuth"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"priorAuth":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","caseId":"00000000-0000-4000-8000-000000000001","status":"active","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","urgency":true,"serviceType":"30","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","diagnosisDescription":"Example prior_auth note","orderingPhysician":"example-orderingphysician","orderingPhysicianNPI":"1234567893","payerId":"87726","payerName":"Example prior_auth","memberId":"W123456789","authorizationNumber":"example-authorizationnumber","submittedAt":"2026-06-08T10:15:30Z","approvedAt":"2026-06-08T10:15:30Z","deniedAt":"2026-06-08T10:15:30Z","denialReason":"example-denialreason","expirationDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for prior authorization workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/{priorAuthId}":{"get":{"operationId":"getPriorAuth","summary":"Get prior authorization","description":"Returns one prior authorization summary when the `priorAuthId` belongs to the organization selected by the bearer API key.\n\n### When to use\nUse this after a create, update, submit, renewal, status, appeal, batch, or internal workflow gives you a trusted prior authorization identifier.\n\n### Before calling\nUse only IDs obtained from the same tenant context. Do not guess identifiers or pass organization selectors in the request.\n\n### Request guidance\nPass `priorAuthId` in the path. No request body or query parameters are declared.\n\n### Request notes\n- `priorAuthId` is a QuickRCM identifier, not a payer authorization number.\n- No request body is declared for this endpoint.\n- The API key determines the tenant.\n\n### Response semantics\nHTTP 200 returns `data.priorAuth`, a local QuickRCM case summary with service, diagnosis, payer/member, authorization-number, denial, expiration, and lifecycle timestamp fields. It does not include raw payer payloads or uploaded document contents.\n\n### Response notes\n- Nullable lifecycle timestamps reflect current local case state.\n- `authorizationNumber` can be null until a payer-facing authorization number is captured.\n- Use document endpoints for upload setup or document validation workflows.\n\n### Errors and retries\nTreat 404 as missing or wrong-organization resource context unless a prior trusted response proves the case should exist. Retry 429 with backoff and retry transient 5xx responses only within normal client retry limits.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant records.\n- 401 and 403 require credential or permission correction.\n- 429 requires backoff rather than tight polling.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"priorAuthId","in":"path","description":"QuickRCM prior authorization case identifier in the path. It must resolve inside the organization selected by the bearer API key."}],"responses":{"200":{"description":"Prior authorization for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"priorAuth":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"caseId":{"type":["string","null"]},"status":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"urgency":{"type":"boolean"},"serviceType":{"type":"string"},"specificService":{"type":"string"},"cptCode":{"type":"string"},"diagnosisCode":{"type":"string"},"diagnosisDescription":{"type":["string","null"]},"orderingPhysician":{"type":["string","null"]},"orderingPhysicianNPI":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"authorizationNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"deniedAt":{"type":["string","null"],"format":"date-time"},"denialReason":{"type":["string","null"]},"expirationDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","caseId","status","patientId","appointmentId","urgency","serviceType","specificService","cptCode","diagnosisCode","diagnosisDescription","orderingPhysician","orderingPhysicianNPI","payerId","payerName","memberId","authorizationNumber","submittedAt","approvedAt","deniedAt","denialReason","expirationDate","createdAt","updatedAt"]}},"required":["priorAuth"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"priorAuth":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","caseId":"00000000-0000-4000-8000-000000000001","status":"active","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","urgency":true,"serviceType":"30","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","diagnosisDescription":"Example prior_auth note","orderingPhysician":"example-orderingphysician","orderingPhysicianNPI":"1234567893","payerId":"87726","payerName":"Example prior_auth","memberId":"W123456789","authorizationNumber":"example-authorizationnumber","submittedAt":"2026-06-08T10:15:30Z","approvedAt":"2026-06-08T10:15:30Z","deniedAt":"2026-06-08T10:15:30Z","denialReason":"example-denialreason","expirationDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prior authorization not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"updatePriorAuth","summary":"Update prior authorization","description":"Updates editable prior authorization fields for an organization-scoped case. The route uses PUT because generated Wasp public API routes do not support PATCH.\n\n### When to use\nUse this to correct service, diagnosis, payer/member, urgency, clinical evidence, medical-necessity, lifecycle, or authorization-number fields on an existing local case.\n\n### Before calling\nRead the current case and decide which supported fields should change. Include `expectedVersion` when your client tracks optimistic concurrency and wants stale-write protection.\n\n### Request guidance\nAll body fields are optional in the public schema, but clients should send only intended updates. Clinical/service fields include `serviceType`, `specificService`, `cptCode`, `diagnosisCode`, `diagnosisDescription`, `clinicalIndication`, `requirements`, and `medicalNecessityLetter`. Provider and payer/member fields include ordering physician values, payer id/name, and member id. Workflow fields include `urgency`, `status`, prediction score, lifecycle dates, denial reason, and authorization number. `metadata` is for sanitized integration metadata. Include `expectedVersion` only when the client has a current version marker for optimistic locking.\n\n### Request notes\n- This is a PUT route with partial editable fields, not a JSON Patch document.\n- `medicalNecessityLetter` is capped at 50000 characters and can contain clinical PHI.\n- `approvalPrediction` is numeric and capped at 100 by the public schema.\n\n### Response semantics\nHTTP 200 returns the updated local `data.priorAuth` summary. This endpoint mutates QuickRCM case state; it does not itself prove payer approval, denial, submission receipt, or document acceptance.\n\n### Response notes\n- Returned status is local QuickRCM case state.\n- Lifecycle timestamp fields can remain null.\n- The response does not include raw external payer content.\n\n### Errors and retries\nTreat 409 as the optimistic-locking conflict declared by OpenAPI, typically requiring a fresh read before another update attempt. Treat 400 as invalid field values, 404 as missing or wrong-tenant case context, 429 as a backoff signal, and 5xx as transient only with bounded retries. Re-read the case after timeouts before retrying to avoid overwriting newer edits.\n\n### Error notes\n- 409 is declared as an optimistic locking conflict, not a generic case-state conflict.\n- 404 can mean the case is outside the API key organization.\n- Retry only after re-reading current state when stale writes are possible.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"priorAuthId","in":"path","description":"QuickRCM prior authorization case identifier in the path. It must resolve inside the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"integer","exclusiveMinimum":0,"description":"Optional optimistic-concurrency version marker. Use it when the client has a current version and wants stale-write conflict detection."},"serviceType":{"type":"string","enum":["IMAGING","SURGERY","THERAPY","DME","MEDICATION","imaging","surgery","therapy","dme","medication","imaging-xray","imaging-lab","imaging-mri","imaging-pet","surgery-oral","surgery-periodontal","surgery-anesthesia","surgery-assistance","therapy-radiation","therapy-inhalation","therapy-chemotherapy","therapy-dialysis","dme-purchased","dme-rental","dme-prosthetics","dme-hearing","dme-oxygen","medication-brand","medication-generic","medication-mail-order"],"description":"Optional replacement service category or detailed service-family enum from the public schema."},"specificService":{"type":"string","minLength":1,"maxLength":250,"description":"Optional replacement service description, capped at 250 characters."},"cptCode":{"type":"string","minLength":1,"maxLength":40,"description":"Optional replacement CPT or procedure code, capped at 40 characters."},"diagnosisCode":{"type":"string","minLength":1,"maxLength":40,"description":"Optional replacement diagnosis code, capped at 40 characters."},"diagnosisDescription":{"type":"string","minLength":1,"maxLength":500,"description":"Optional replacement diagnosis description, capped at 500 characters."},"orderingPhysician":{"type":"string","minLength":1,"maxLength":200,"description":"Optional ordering physician name or display label, capped at 200 characters."},"orderingPhysicianNPI":{"type":"string","minLength":1,"maxLength":20,"description":"Optional ordering physician National Provider Identifier, capped at 20 characters."},"clinicalIndication":{"type":"string","minLength":1,"maxLength":5000,"description":"Optional clinical rationale, capped at 5000 characters. Avoid raw transcripts or unnecessary PHI."},"payerId":{"type":"string","minLength":1,"maxLength":120,"description":"Optional payer identifier associated with the case, capped at 120 characters."},"payerName":{"type":"string","minLength":1,"maxLength":200,"description":"Optional payer display name, capped at 200 characters."},"memberId":{"type":"string","minLength":1,"maxLength":120,"description":"Optional payer member or subscriber identifier, capped at 120 characters. Treat as PHI-adjacent."},"urgency":{"type":"boolean","description":"Optional boolean urgent-workflow marker for the local prior authorization case."},"requirements":{"description":"Optional structured requirements object for local case tracking. Do not include raw vendor payloads."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional sanitized integration metadata object; never store credentials, tokens, raw EDI, upload URLs, or storage secrets."},"status":{"type":"string","enum":["pending_submission","submitted","approved","denied","more_info_required","draft","in_review","partially_approved","expired","appealed","appeal_approved","appeal_denied","cancelled","voided"],"description":"Optional local prior authorization workflow status from the public status enum."},"approvalPrediction":{"type":"number","minimum":0,"maximum":100,"description":"Optional numeric prediction score capped at 100. Do not present it as a payer decision."},"medicalNecessityLetter":{"type":"string","minLength":1,"maxLength":50000,"description":"Optional clinical letter text, capped at 50000 characters. Do not include transcripts, raw payer payloads, or credentials."},"submittedAt":{"type":"string","format":"date-time","description":"Optional ISO datetime recording when the case was submitted in local workflow state."},"approvedAt":{"type":"string","format":"date-time","description":"Optional ISO datetime recording local approval state evidence."},"deniedAt":{"type":"string","format":"date-time","description":"Optional ISO datetime recording local denial state evidence."},"expirationDate":{"type":"string","format":"date-time","description":"Optional ISO datetime for authorization expiration when known."},"denialReason":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional denial reason text capped at 2000 characters. Keep it sanitized."},"authorizationNumber":{"type":"string","minLength":1,"maxLength":100,"description":"Optional payer-facing authorization number when captured."}}},"example":{"expectedVersion":1,"serviceType":"IMAGING","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","diagnosisDescription":"Example prior_auth note","orderingPhysician":"example-orderingphysician","orderingPhysicianNPI":"1234567893"}}},"description":"All body fields are optional in the public schema, but clients should send only intended updates. Clinical/service fields include `serviceType`, `specificService`, `cptCode`, `diagnosisCode`, `diagnosisDescription`, `clinicalIndication`, `requirements`, and `medicalNecessityLetter`. Provider and payer/member fields include ordering physician values, payer id/name, and member id. Workflow fields include `urgency`, `status`, prediction score, lifecycle dates, denial reason, and authorization number. `metadata` is for sanitized integration metadata. Include `expectedVersion` only when the client has a current version marker for optimistic locking."},"responses":{"200":{"description":"Updated prior authorization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"priorAuth":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"caseId":{"type":["string","null"]},"status":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"urgency":{"type":"boolean"},"serviceType":{"type":"string"},"specificService":{"type":"string"},"cptCode":{"type":"string"},"diagnosisCode":{"type":"string"},"diagnosisDescription":{"type":["string","null"]},"orderingPhysician":{"type":["string","null"]},"orderingPhysicianNPI":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"authorizationNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"deniedAt":{"type":["string","null"],"format":"date-time"},"denialReason":{"type":["string","null"]},"expirationDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","caseId","status","patientId","appointmentId","urgency","serviceType","specificService","cptCode","diagnosisCode","diagnosisDescription","orderingPhysician","orderingPhysicianNPI","payerId","payerName","memberId","authorizationNumber","submittedAt","approvedAt","deniedAt","denialReason","expirationDate","createdAt","updatedAt"]}},"required":["priorAuth"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"priorAuth":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","caseId":"00000000-0000-4000-8000-000000000001","status":"active","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","urgency":true,"serviceType":"30","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","diagnosisDescription":"Example prior_auth note","orderingPhysician":"example-orderingphysician","orderingPhysicianNPI":"1234567893","payerId":"87726","payerName":"Example prior_auth","memberId":"W123456789","authorizationNumber":"example-authorizationnumber","submittedAt":"2026-06-08T10:15:30Z","approvedAt":"2026-06-08T10:15:30Z","deniedAt":"2026-06-08T10:15:30Z","denialReason":"example-denialreason","expirationDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prior authorization not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Optimistic locking conflict.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/{priorAuthId}/submit":{"put":{"operationId":"submitPriorAuth","summary":"Submit prior authorization","description":"Submits an existing prior authorization case for payer review according to the public OpenAPI description and returns the updated local case summary.\n\n### When to use\nUse this after the prior authorization case has complete service, diagnosis, payer/member, ordering-provider, and clinical evidence required by the workflow.\n\n### Before calling\nRead the case, confirm it belongs to the same tenant, and verify that required supporting documents or clinical fields are complete in your workflow. No request body fields are declared.\n\n### Request guidance\nPass only `priorAuthId` in the path. Do not send payer portal credentials, raw vendor payloads, or document bytes to this endpoint.\n\n### Request notes\n- No JSON request body fields are declared.\n- Use document endpoints separately for supporting-document upload setup and validation.\n- Do not put credentials or raw payer payloads in path or logs.\n\n### Response semantics\nHTTP 200 returns `data.priorAuth` after submission processing. Document the response as local QuickRCM case state after submit, not payer approval, denial, final authorization, or guaranteed external receipt.\n\n### Response notes\n- A successful response is not a payer approval.\n- `submittedAt` and status fields are local QuickRCM state fields.\n- Follow downstream status, document, or appeal workflows for later evidence.\n\n### Errors and retries\nTreat 402 as insufficient credits, 400 as invalid state or request shape, 404 as missing or wrong-tenant case context, 429 as a backoff signal, and 5xx as transient only with bounded retries. After a timeout, re-read the case before retrying to avoid duplicate workflow actions.\n\n### Error notes\n- 402 is declared for insufficient credits.\n- 404 can intentionally hide wrong-tenant cases.\n- Retry only after checking current case state if the previous response was lost.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"priorAuthId","in":"path","description":"QuickRCM prior authorization case identifier to submit for review."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}},"example":{}}},"description":"Pass only `priorAuthId` in the path. Do not send payer portal credentials, raw vendor payloads, or document bytes to this endpoint."},"responses":{"200":{"description":"Submitted prior authorization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"priorAuth":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"caseId":{"type":["string","null"]},"status":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"urgency":{"type":"boolean"},"serviceType":{"type":"string"},"specificService":{"type":"string"},"cptCode":{"type":"string"},"diagnosisCode":{"type":"string"},"diagnosisDescription":{"type":["string","null"]},"orderingPhysician":{"type":["string","null"]},"orderingPhysicianNPI":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"authorizationNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"deniedAt":{"type":["string","null"],"format":"date-time"},"denialReason":{"type":["string","null"]},"expirationDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","caseId","status","patientId","appointmentId","urgency","serviceType","specificService","cptCode","diagnosisCode","diagnosisDescription","orderingPhysician","orderingPhysicianNPI","payerId","payerName","memberId","authorizationNumber","submittedAt","approvedAt","deniedAt","denialReason","expirationDate","createdAt","updatedAt"]}},"required":["priorAuth"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"priorAuth":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","caseId":"00000000-0000-4000-8000-000000000001","status":"submitted","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","urgency":true,"serviceType":"30","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","diagnosisDescription":"Example prior_auth note","orderingPhysician":"example-orderingphysician","orderingPhysicianNPI":"1234567893","payerId":"87726","payerName":"Example prior_auth","memberId":"W123456789","authorizationNumber":"example-authorizationnumber","submittedAt":"2026-06-08T10:15:30Z","approvedAt":"2026-06-08T10:15:30Z","deniedAt":"2026-06-08T10:15:30Z","denialReason":"example-denialreason","expirationDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for submission.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prior authorization not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/drafts":{"post":{"operationId":"savePriorAuthDraft","summary":"Save prior authorization draft","description":"Creates or updates a draft prior authorization for the authenticated organization according to the public operation description.\n\n### When to use\nUse this for draft-save flows that need to create or update a local prior authorization draft using the request fields exposed by the public schema. For finalized case creation semantics, use `createPriorAuth`.\n\n### Before calling\nConfirm the caller has Prior Authorization access. Prepare the same required create-case fields exposed by the `allOf` request schema, including the cross-field payer rule: provide either `payerId` or `payerName`. Include `payerName` when a supplied payer ID may not resolve, and include `priorAuthId` only when updating a trusted draft or case from the same tenant.\n\n### Request guidance\nThe current OpenAPI body is an `allOf` schema containing the create prior authorization request fields plus optional `priorAuthId`. Required fields mirror the create-case schema: `patientFirstName`, `patientLastName`, `patientDOB`, `serviceType`, `specificService`, `cptCode`, `diagnosisCode`, and `orderingPhysician`, and the public contract additionally requires at least one of `payerId` or `payerName`. Keep clinical, payer, requirement-check, and metadata fields sanitized.\n\n### Request notes\n- The public schema exposes named draft fields through an `allOf` body, not an empty object.\n- Use `priorAuthId` only for a trusted same-tenant draft/update target.\n- Keep draft content PHI-minimal and sanitized; do not include raw payer payloads, upload URLs, tokens, or credentials.\n- The draft-save body inherits the create-case payer rule: provide `payerId` or `payerName`, and provide `payerName` explicitly when payer ID lookup may not resolve.\n\n### Response semantics\nHTTP 200 returns `data.priorAuth`, a saved local draft case summary. It is not payer submission, approval, denial, or receipt.\n\n### Response notes\n- `data.priorAuth` is local draft state.\n- The endpoint does not submit the case externally.\n- Use submitPriorAuth when the case is ready for submission workflow.\n\n### Errors and retries\nTreat 402 as insufficient credits, 400 as invalid draft request shape, 401/403 as credential or tenant authorization failures, 429 as a backoff signal, and 500 as transient only with bounded retries. Re-read or search current draft state after timeouts before sending another draft-save request.\n\n### Error notes\n- 402 is declared for insufficient credits.\n- 400 can indicate missing required create-style fields or unsupported request shape.\n- After a lost response, reconcile current draft state before sending another draft-save request.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"patientFirstName":{"type":"string","minLength":1,"maxLength":100,"description":"Required patient first name for the draft. Use synthetic values in examples."},"patientLastName":{"type":"string","minLength":1,"maxLength":100,"description":"Required patient last name for the draft. Use synthetic values in examples."},"patientDOB":{"type":"string","minLength":1,"description":"Required patient date of birth as YYYY-MM-DD or another ISO date string."},"mrn":{"type":"string","minLength":1,"maxLength":120,"description":"Optional medical record number. Treat as patient-identifying data."},"appointmentId":{"type":"string","minLength":1,"description":"Optional QuickRCM appointment identifier to link the draft to a scheduled encounter."},"serviceType":{"type":"string","enum":["IMAGING","SURGERY","THERAPY","DME","MEDICATION","imaging","surgery","therapy","dme","medication","imaging-xray","imaging-lab","imaging-mri","imaging-pet","surgery-oral","surgery-periodontal","surgery-anesthesia","surgery-assistance","therapy-radiation","therapy-inhalation","therapy-chemotherapy","therapy-dialysis","dme-purchased","dme-rental","dme-prosthetics","dme-hearing","dme-oxygen","medication-brand","medication-generic","medication-mail-order"],"description":"Required service category or detailed service family enum from the public schema."},"specificService":{"type":"string","minLength":1,"maxLength":250,"description":"Required human-readable service description, capped at 250 characters."},"cptCode":{"type":"string","minLength":1,"maxLength":40,"description":"Required CPT or procedure code, capped at 40 characters."},"diagnosisCode":{"type":"string","minLength":1,"maxLength":40,"description":"Required diagnosis code, capped at 40 characters."},"diagnosisDescription":{"type":"string","minLength":1,"maxLength":500,"description":"Optional diagnosis description, capped at 500 characters."},"orderingPhysician":{"type":"string","minLength":1,"maxLength":200,"description":"Required ordering physician name or display label, capped at 200 characters."},"orderingPhysicianNPI":{"type":"string","minLength":1,"maxLength":20,"description":"Optional ordering physician National Provider Identifier, capped at 20 characters."},"clinicalIndication":{"type":"string","minLength":1,"maxLength":5000,"description":"Optional clinical rationale, capped at 5000 characters. Avoid raw transcripts."},"payerId":{"type":"string","minLength":1,"maxLength":120,"description":"Conditionally required payer identifier when `payerName` is omitted, capped at 120 characters. Because draft save reuses the create-case schema, omitting both payer fields fails validation."},"payerName":{"type":"string","minLength":1,"maxLength":200,"description":"Conditionally required payer display name when `payerId` is omitted or may not resolve, capped at 200 characters. Use synthetic payer names in examples."},"memberId":{"type":"string","minLength":1,"maxLength":120,"description":"Optional payer member or subscriber identifier, capped at 120 characters. Treat as PHI-adjacent."},"placeOfService":{"type":"string","minLength":1,"maxLength":120,"description":"Optional place-of-service label or description, capped at 120 characters."},"placeOfServiceCode":{"type":"string","minLength":1,"maxLength":10,"description":"Optional short place-of-service code, capped at 10 characters."},"urgency":{"type":"boolean","description":"Optional boolean indicating urgent local workflow handling."},"isAuthRequiredResult":{"type":"boolean","description":"Optional copied boolean result from a prior-auth requirement check."},"isAuthRequiredPolicyName":{"type":"string","minLength":1,"maxLength":250,"description":"Optional policy name copied from a requirement check, capped at 250 characters."},"isAuthRequiredPolicyDescription":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional policy description copied from a requirement check, capped at 2000 characters."},"isAuthRequiredRequirements":{"description":"Optional structured requirements copied from a requirement check. Do not include raw payer payloads."},"isAuthRequiredEvidenceSufficiency":{"description":"Optional structured evidence-sufficiency object copied from a requirement check."},"requirements":{"description":"Optional structured draft requirements object. Keep it sanitized."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional integration metadata object. Do not include credentials, tokens, raw EDI, upload URLs, or storage secrets."}},"required":["patientFirstName","patientLastName","patientDOB","serviceType","specificService","cptCode","diagnosisCode","orderingPhysician"]},{"type":"object","properties":{"priorAuthId":{"type":"string","minLength":1,"description":"Optional QuickRCM prior authorization identifier when updating an existing local draft or case in the authenticated organization."}}}]},"example":{"patientFirstName":"Example save_prior_auth_draft","patientLastName":"Example save_prior_auth_draft","patientDOB":"1984-03-22","serviceType":"IMAGING","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","orderingPhysician":"example-orderingphysician","mrn":"example-mrn","appointmentId":"00000000-0000-4000-8000-000000000001","diagnosisDescription":"Example save_prior_auth_draft note","orderingPhysicianNPI":"1234567893","clinicalIndication":"example-clinicalindication","payerId":"87726","payerName":"Example save_prior_auth_draft","memberId":"W123456789","priorAuthId":"00000000-0000-4000-8000-000000000001"}}},"description":"The current OpenAPI body is an `allOf` schema containing the create prior authorization request fields plus optional `priorAuthId`. Required fields mirror the create-case schema: `patientFirstName`, `patientLastName`, `patientDOB`, `serviceType`, `specificService`, `cptCode`, `diagnosisCode`, and `orderingPhysician`, and the public contract additionally requires at least one of `payerId` or `payerName`. Keep clinical, payer, requirement-check, and metadata fields sanitized."},"responses":{"200":{"description":"Saved prior authorization draft.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"priorAuth":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"caseId":{"type":["string","null"]},"status":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"urgency":{"type":"boolean"},"serviceType":{"type":"string"},"specificService":{"type":"string"},"cptCode":{"type":"string"},"diagnosisCode":{"type":"string"},"diagnosisDescription":{"type":["string","null"]},"orderingPhysician":{"type":["string","null"]},"orderingPhysicianNPI":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"authorizationNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"deniedAt":{"type":["string","null"],"format":"date-time"},"denialReason":{"type":["string","null"]},"expirationDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","caseId","status","patientId","appointmentId","urgency","serviceType","specificService","cptCode","diagnosisCode","diagnosisDescription","orderingPhysician","orderingPhysicianNPI","payerId","payerName","memberId","authorizationNumber","submittedAt","approvedAt","deniedAt","denialReason","expirationDate","createdAt","updatedAt"]}},"required":["priorAuth"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"priorAuth":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","caseId":"00000000-0000-4000-8000-000000000001","status":"active","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","urgency":true,"serviceType":"30","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","diagnosisDescription":"Example save_prior_auth_draft note","orderingPhysician":"example-orderingphysician","orderingPhysicianNPI":"1234567893","payerId":"87726","payerName":"Example save_prior_auth_draft","memberId":"W123456789","authorizationNumber":"example-authorizationnumber","submittedAt":"2026-06-08T10:15:30Z","approvedAt":"2026-06-08T10:15:30Z","deniedAt":"2026-06-08T10:15:30Z","denialReason":"example-denialreason","expirationDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for prior authorization workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/{priorAuthId}/status":{"put":{"operationId":"updatePriorAuthStatus","summary":"Update prior authorization status","description":"Updates only the status of one organization-scoped prior authorization case, with an optional reason.\n\n### When to use\nUse this when an integration or staff workflow needs to record a status transition without changing service, payer, clinical, or appeal fields.\n\n### Before calling\nLoad the current case and choose one status from the public prior authorization status enum. Prepare a sanitized `reason` when the transition needs staff-readable context.\n\n### Request guidance\n`status` is required and must be one of the public status enum values. `reason` is optional and capped at 2000 characters. Do not use this endpoint for bulk status changes; use `bulkUpdatePriorAuthStatus` instead.\n\n### Request notes\n- Valid status values include `pending_submission`, `submitted`, `approved`, `denied`, `more_info_required`, `draft`, `in_review`, `partially_approved`, `expired`, `appealed`, `appeal_approved`, `appeal_denied`, `cancelled`, and `voided`.\n- `reason` should not contain raw payer payloads or unnecessary PHI.\n- Use the path `priorAuthId` as the only resource selector.\n\n### Response semantics\nHTTP 200 returns the updated local `data.priorAuth`. It records QuickRCM workflow state and should not be described as a payer communication by itself.\n\n### Response notes\n- The response is the updated local case summary.\n- Approval or denial statuses should reflect evidence captured by the caller or workflow.\n- No document upload or appeal is created by this endpoint.\n\n### Errors and retries\nTreat 400 as invalid status or reason shape, 404 as missing or wrong-tenant case context, 429 as a backoff signal, and 5xx as retryable only with bounded retries. Re-read case state after timeouts before replaying a status transition.\n\n### Error notes\n- 400 means the status body failed validation.\n- 404 can mean the case is not in the API key organization.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"priorAuthId","in":"path","description":"QuickRCM prior authorization case identifier in the path. It must resolve inside the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending_submission","submitted","approved","denied","more_info_required","draft","in_review","partially_approved","expired","appealed","appeal_approved","appeal_denied","cancelled","voided"],"description":"Required target prior authorization workflow status from the public enum."},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional status-transition reason, capped at 2000 characters. Keep it sanitized."}},"required":["status"]},"example":{"status":"pending_submission","reason":"example-reason"}}},"description":"`status` is required and must be one of the public status enum values. `reason` is optional and capped at 2000 characters. Do not use this endpoint for bulk status changes; use `bulkUpdatePriorAuthStatus` instead."},"responses":{"200":{"description":"Updated prior authorization status.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"priorAuth":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"caseId":{"type":["string","null"]},"status":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"urgency":{"type":"boolean"},"serviceType":{"type":"string"},"specificService":{"type":"string"},"cptCode":{"type":"string"},"diagnosisCode":{"type":"string"},"diagnosisDescription":{"type":["string","null"]},"orderingPhysician":{"type":["string","null"]},"orderingPhysicianNPI":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"authorizationNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"deniedAt":{"type":["string","null"],"format":"date-time"},"denialReason":{"type":["string","null"]},"expirationDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","caseId","status","patientId","appointmentId","urgency","serviceType","specificService","cptCode","diagnosisCode","diagnosisDescription","orderingPhysician","orderingPhysicianNPI","payerId","payerName","memberId","authorizationNumber","submittedAt","approvedAt","deniedAt","denialReason","expirationDate","createdAt","updatedAt"]}},"required":["priorAuth"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"priorAuth":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","caseId":"00000000-0000-4000-8000-000000000001","status":"active","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","urgency":true,"serviceType":"30","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","diagnosisDescription":"Example prior_auth_statu note","orderingPhysician":"example-orderingphysician","orderingPhysicianNPI":"1234567893","payerId":"87726","payerName":"Example prior_auth_statu","memberId":"W123456789","authorizationNumber":"example-authorizationnumber","submittedAt":"2026-06-08T10:15:30Z","approvedAt":"2026-06-08T10:15:30Z","deniedAt":"2026-06-08T10:15:30Z","denialReason":"example-denialreason","expirationDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prior authorization not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/{priorAuthId}/renew":{"post":{"operationId":"renewPriorAuth","summary":"Create prior authorization renewal","description":"Creates a local renewal case from an approved or expired prior authorization and returns the renewal case summary.\n\n### When to use\nUse this when an existing approved or expired authorization needs a new local renewal workflow instead of overwriting the original case.\n\n### Before calling\nConfirm the source prior authorization belongs to the same tenant and is approved or expired according to the public description. If your client sends `idempotencyKey`, use a non-PHI caller correlation value and reconcile local state after lost responses; the OpenAPI field alone does not promise server-side deduplication.\n\n### Request guidance\n`idempotencyKey` is optional and capped at 200 characters. Do not include PHI in idempotency keys. No other body fields are declared.\n\n### Request notes\n- `idempotencyKey` is an optional caller-provided marker capped at 200 characters; do not include PHI.\n- The source case remains a separate record from the renewal case.\n- The OpenAPI description limits the source to approved or expired cases.\n\n### Response semantics\nHTTP 202 means the renewal was accepted and created locally; `data.priorAuth` contains the local renewal case. It does not prove payer renewal approval.\n\n### Response notes\n- 202 means local renewal accepted and created.\n- The response returns a `priorAuth` summary.\n- A renewal case is not a payer approval.\n\n### Errors and retries\nTreat 409 as the documented signal that a renewal already exists, 402 as insufficient credits, 403 as a tenant or permission failure, 429 as a backoff signal, and 5xx as transient only with bounded retries. Re-read local state after timeouts before retrying.\n\n### Error notes\n- 409 is declared as `A renewal already exists`.\n- 402 is declared for insufficient credits.\n- Use backoff for 429 responses.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"priorAuthId","in":"path","description":"QuickRCM source prior authorization identifier to renew."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller-provided request marker capped at 200 characters. Do not include PHI; do not document it as a server-side deduplication guarantee."}}},"example":{"idempotencyKey":"example-idempotencykey"}}},"description":"`idempotencyKey` is optional and capped at 200 characters. Do not include PHI in idempotency keys. No other body fields are declared."},"responses":{"202":{"description":"Renewal accepted and created locally.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"priorAuth":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"caseId":{"type":["string","null"]},"status":{"type":"string"},"patientId":{"type":"string"},"appointmentId":{"type":["string","null"]},"urgency":{"type":"boolean"},"serviceType":{"type":"string"},"specificService":{"type":"string"},"cptCode":{"type":"string"},"diagnosisCode":{"type":"string"},"diagnosisDescription":{"type":["string","null"]},"orderingPhysician":{"type":["string","null"]},"orderingPhysicianNPI":{"type":["string","null"]},"payerId":{"type":["string","null"]},"payerName":{"type":["string","null"]},"memberId":{"type":["string","null"]},"authorizationNumber":{"type":["string","null"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"approvedAt":{"type":["string","null"],"format":"date-time"},"deniedAt":{"type":["string","null"],"format":"date-time"},"denialReason":{"type":["string","null"]},"expirationDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","caseId","status","patientId","appointmentId","urgency","serviceType","specificService","cptCode","diagnosisCode","diagnosisDescription","orderingPhysician","orderingPhysicianNPI","payerId","payerName","memberId","authorizationNumber","submittedAt","approvedAt","deniedAt","denialReason","expirationDate","createdAt","updatedAt"]}},"required":["priorAuth"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"priorAuth":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","caseId":"00000000-0000-4000-8000-000000000001","status":"active","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","urgency":true,"serviceType":"30","specificService":"example-specificservice","cptCode":"example-cptcode","diagnosisCode":"example-diagnosiscode","diagnosisDescription":"Example renew_prior_auth note","orderingPhysician":"example-orderingphysician","orderingPhysicianNPI":"1234567893","payerId":"87726","payerName":"Example renew_prior_auth","memberId":"W123456789","authorizationNumber":"example-authorizationnumber","submittedAt":"2026-06-08T10:15:30Z","approvedAt":"2026-06-08T10:15:30Z","deniedAt":"2026-06-08T10:15:30Z","denialReason":"example-denialreason","expirationDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for renewal.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"409":{"description":"A renewal already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/{priorAuthId}/appeals":{"post":{"operationId":"createPriorAuthAppeal","summary":"Create prior authorization appeal","description":"Creates a local appeal for a denied prior authorization in the authenticated organization.\n\n### When to use\nUse this when a denied prior authorization needs appeal tracking, appeal reason capture, optional appeal-letter text, and optional peer-to-peer request tracking.\n\n### Before calling\nConfirm the source prior authorization belongs to the tenant and is denied. Prepare `appealLevel`, `appealType`, and a sanitized `appealReason`. If using `idempotencyKey`, treat it as a caller-provided request marker, not a documented deduplication guarantee.\n\n### Request guidance\n`appealLevel`, `appealType`, and `appealReason` are required. `appealLetter`, `p2pRequested`, and `idempotencyKey` are optional. Keep appeal text clinically necessary and free of raw payer payloads, transcripts, credentials, and storage secrets.\n\n### Request notes\n- `appealLevel` must be one of `PA_FIRST_LEVEL`, `PA_SECOND_LEVEL`, `PA_EXTERNAL_REVIEW`, or `PA_STATE_HEARING`.\n- `appealType` must be one of the PA appeal type enum values exposed by the schema.\n- `appealLetter` is capped at 50000 characters and can contain PHI.\n- `idempotencyKey` is optional and should be free of PHI; OpenAPI does not define server-side deduplication behavior.\n\n### Response semantics\nHTTP 201 returns `data.appeal`, a local QuickRCM prior authorization appeal record. It does not prove external appeal submission, peer-to-peer scheduling, or payer overturn.\n\n### Response notes\n- `data.appeal` is local tracking state.\n- Peer-to-peer fields are tracking fields, not evidence that a payer scheduled a call.\n- Use updatePriorAuthAppeal to record later status, P2P, or decision outcomes.\n\n### Errors and retries\nTreat 409 as the documented signal that an active appeal already exists, 400 as invalid appeal fields, 401/403 as credential or tenant failures, 429 as a backoff signal, and 5xx as transient only with bounded retries. After timeouts, re-read local appeals before creating another appeal.\n\n### Error notes\n- 409 is declared as `An active appeal already exists`.\n- 400 can indicate invalid appeal enum values or missing appeal reason.\n- Do not create duplicate appeals after a lost response without checking local state.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"priorAuthId","in":"path","description":"QuickRCM prior authorization case identifier in the path. It must resolve inside the authenticated organization and be eligible for local appeal creation."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"appealLevel":{"type":"string","enum":["PA_FIRST_LEVEL","PA_SECOND_LEVEL","PA_EXTERNAL_REVIEW","PA_STATE_HEARING"],"description":"Required appeal level enum: first level, second level, external review, or state hearing."},"appealType":{"type":"string","enum":["PA_APPEAL_MEDICAL_NECESSITY","PA_APPEAL_CODING_ERROR","PA_APPEAL_MISSING_INFO_RESUBMIT","PA_APPEAL_CLINICAL_REVIEW","PA_APPEAL_ADMIN_ERROR"],"description":"Required appeal category enum explaining why the denial is being challenged."},"appealReason":{"type":"string","minLength":1,"maxLength":5000,"description":"Required appeal reason text capped at 5000 characters. Keep it clinically relevant and sanitized."},"appealLetter":{"type":"string","minLength":1,"maxLength":50000,"description":"Optional appeal letter text capped at 50000 characters. Do not include raw payer payloads or transcripts."},"p2pRequested":{"type":"boolean","description":"Optional flag indicating whether peer-to-peer review is requested for local tracking."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller-provided request marker capped at 200 characters and free of PHI. Do not document it as a deduplication guarantee."}},"required":["appealLevel","appealType","appealReason"]},"example":{"appealLevel":"PA_FIRST_LEVEL","appealType":"PA_APPEAL_MEDICAL_NECESSITY","appealReason":"example-appealreason","appealLetter":"example-appealletter","p2pRequested":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`appealLevel`, `appealType`, and `appealReason` are required. `appealLetter`, `p2pRequested`, and `idempotencyKey` are optional. Keep appeal text clinically necessary and free of raw payer payloads, transcripts, credentials, and storage secrets."},"responses":{"201":{"description":"Created prior authorization appeal.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"priorAuthId":{"type":"string"},"appealLevel":{"type":"string"},"appealType":{"type":"string"},"status":{"type":"string"},"denialDate":{"type":["string","null"],"format":"date-time"},"appealDeadline":{"type":["string","null"],"format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"},"decidedAt":{"type":["string","null"],"format":"date-time"},"appealReason":{"type":["string","null"]},"p2pRequested":{"type":"boolean"},"p2pScheduledAt":{"type":["string","null"],"format":"date-time"},"p2pCompletedAt":{"type":["string","null"],"format":"date-time"},"p2pOutcome":{"type":["string","null"]},"decisionOutcome":{"type":["string","null"]},"decisionReason":{"type":["string","null"]},"newAuthNumber":{"type":["string","null"]},"newExpirationDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","priorAuthId","appealLevel","appealType","status","denialDate","appealDeadline","submittedAt","decidedAt","appealReason","p2pRequested","p2pScheduledAt","p2pCompletedAt","p2pOutcome","decisionOutcome","decisionReason","newAuthNumber","newExpirationDate","createdAt","updatedAt"]}},"required":["appeal"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"],"additionalProperties":{}}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","priorAuthId":"00000000-0000-4000-8000-000000000001","appealLevel":"example-appeallevel","appealType":"example-appealtype","status":"active","denialDate":"2026-06-08T10:15:30Z","appealDeadline":"2026-06-08T10:15:30Z","submittedAt":"2026-06-08T10:15:30Z","decidedAt":"2026-06-08T10:15:30Z","appealReason":"example-appealreason","p2pRequested":true,"p2pScheduledAt":"2026-06-08T10:15:30Z","p2pCompletedAt":"2026-06-08T10:15:30Z","p2pOutcome":"example-p2poutcome","decisionOutcome":"example-decisionoutcome","decisionReason":"example-decisionreason","newAuthNumber":"example-newauthnumber","newExpirationDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"409":{"description":"An active appeal already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/appeals/{appealId}":{"put":{"operationId":"updatePriorAuthAppeal","summary":"Update prior authorization appeal","description":"Updates a local prior authorization appeal and any related local case status according to the public operation description.\n\n### When to use\nUse this to record appeal status changes, peer-to-peer scheduling/completion, payer decision notes, a new authorization number, or a new expiration date.\n\n### Before calling\nLoad the appeal in the same tenant and decide which supported fields need to change. Keep decision and P2P notes sanitized.\n\n### Request guidance\nSupported body fields are `status`, `p2pScheduledAt`, `p2pCompletedAt`, `p2pOutcome`, `decisionOutcome`, `decisionReason`, `newAuthNumber`, and `newExpirationDate`. Send ISO datetime strings for date-time fields.\n\n### Request notes\n- `status` must be one of the public PA appeal status enum values.\n- `newAuthNumber` is capped at 100 characters.\n- `decisionReason` is capped at 5000 characters and should not contain raw payer payloads.\n\n### Response semantics\nHTTP 200 returns `data.appeal`, the updated local appeal record. The endpoint records tracking and decision evidence in QuickRCM; it does not submit an appeal externally by itself.\n\n### Response notes\n- Returned appeal data is local tracking state.\n- New authorization fields should be treated as captured evidence, not generated by QuickRCM.\n- Related prior authorization status changes are local case state.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant appeal context, 400 as invalid enum/date/text values, 429 as a backoff signal, and 5xx as transient only with bounded retries. Re-read the appeal after timeouts before retrying to avoid overwriting newer updates.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant appeals.\n- 400 can indicate invalid status or malformed date-time fields.\n- Use backoff for 429 responses.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appealId","in":"path","description":"QuickRCM prior authorization appeal identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["PA_APPEAL_PENDING","PA_APPEAL_SUBMITTED","PA_APPEAL_IN_REVIEW","PA_APPEAL_P2P_SCHEDULED","PA_APPEAL_P2P_COMPLETED","PA_APPEAL_APPROVED","PA_APPEAL_DENIED","PA_APPEAL_ESCALATED"],"description":"Optional local appeal workflow status from the PA appeal status enum, such as pending, submitted, in review, peer-to-peer scheduled/completed, approved, denied, or escalated."},"p2pScheduledAt":{"type":"string","format":"date-time","description":"Optional ISO datetime when peer-to-peer review is scheduled."},"p2pCompletedAt":{"type":"string","format":"date-time","description":"Optional ISO datetime when peer-to-peer review was completed."},"p2pOutcome":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional peer-to-peer outcome text capped at 2000 characters."},"decisionOutcome":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional decision outcome text capped at 2000 characters."},"decisionReason":{"type":"string","minLength":1,"maxLength":5000,"description":"Optional decision reason text capped at 5000 characters. Keep it sanitized."},"newAuthNumber":{"type":"string","minLength":1,"maxLength":100,"description":"Optional new authorization number captured after appeal activity."},"newExpirationDate":{"type":"string","format":"date-time","description":"Optional ISO date or datetime for the new authorization expiration date."}}},"example":{"status":"PA_APPEAL_PENDING","p2pScheduledAt":"2026-06-08T10:15:30Z","p2pCompletedAt":"2026-06-08T10:15:30Z","p2pOutcome":"example-p2poutcome","decisionOutcome":"example-decisionoutcome","decisionReason":"example-decisionreason","newAuthNumber":"example-newauthnumber","newExpirationDate":"2026-06-08T10:15:30Z"}}},"description":"Supported body fields are `status`, `p2pScheduledAt`, `p2pCompletedAt`, `p2pOutcome`, `decisionOutcome`, `decisionReason`, `newAuthNumber`, and `newExpirationDate`. Send ISO datetime strings for date-time fields."},"responses":{"200":{"description":"Updated prior authorization appeal.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appeal":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"priorAuthId":{"type":"string"},"appealLevel":{"type":"string"},"appealType":{"type":"string"},"status":{"type":"string"},"denialDate":{"type":["string","null"],"format":"date-time"},"appealDeadline":{"type":["string","null"],"format":"date-time"},"submittedAt":{"type":["string","null"],"format":"date-time"},"decidedAt":{"type":["string","null"],"format":"date-time"},"appealReason":{"type":["string","null"]},"p2pRequested":{"type":"boolean"},"p2pScheduledAt":{"type":["string","null"],"format":"date-time"},"p2pCompletedAt":{"type":["string","null"],"format":"date-time"},"p2pOutcome":{"type":["string","null"]},"decisionOutcome":{"type":["string","null"]},"decisionReason":{"type":["string","null"]},"newAuthNumber":{"type":["string","null"]},"newExpirationDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","priorAuthId","appealLevel","appealType","status","denialDate","appealDeadline","submittedAt","decidedAt","appealReason","p2pRequested","p2pScheduledAt","p2pCompletedAt","p2pOutcome","decisionOutcome","decisionReason","newAuthNumber","newExpirationDate","createdAt","updatedAt"]}},"required":["appeal"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"],"additionalProperties":{}}},"required":["success","data","meta"]},"example":{"success":true,"data":{"appeal":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","priorAuthId":"00000000-0000-4000-8000-000000000001","appealLevel":"example-appeallevel","appealType":"example-appealtype","status":"active","denialDate":"2026-06-08T10:15:30Z","appealDeadline":"2026-06-08T10:15:30Z","submittedAt":"2026-06-08T10:15:30Z","decidedAt":"2026-06-08T10:15:30Z","appealReason":"example-appealreason","p2pRequested":true,"p2pScheduledAt":"2026-06-08T10:15:30Z","p2pCompletedAt":"2026-06-08T10:15:30Z","p2pOutcome":"example-p2poutcome","decisionOutcome":"example-decisionoutcome","decisionReason":"example-decisionreason","newAuthNumber":"example-newauthnumber","newExpirationDate":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Appeal not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/bulk/status":{"put":{"operationId":"bulkUpdatePriorAuthStatus","summary":"Bulk update prior authorization status","description":"Bulk-updates status values for prior authorization cases within the authenticated organization.\n\n### When to use\nUse this for controlled internal reconciliation or workflow operations where a set of known prior authorization IDs needs the same status.\n\n### Before calling\nBuild the `ids` list from trusted QuickRCM responses in the same tenant and choose one valid target status. Prepare a sanitized shared `reason` if needed.\n\n### Request guidance\n`ids` and `status` are required. `reason` is optional and capped at 2000 characters. Keep batches scoped and do not mix IDs from different tenants or workflows.\n\n### Request notes\n- `ids` is an array of QuickRCM prior authorization identifiers.\n- All IDs must belong to the organization selected by the API key.\n- The same `reason` applies to the bulk transition.\n\n### Response semantics\nHTTP 200 returns a generic bulk status update result object. The current OpenAPI schema does not declare per-ID result fields, so public docs should not promise counts, skipped IDs, or itemized errors unless the schema changes.\n\n### Response notes\n- The generated schema exposes `data` as a generic object.\n- Do not document per-record status details until the OpenAPI response schema exposes them.\n- The endpoint changes local workflow state, not payer state.\n\n### Errors and retries\nTreat 400 as invalid IDs or status, 401/403 as credential or tenant failures, 429 as a backoff signal, and 5xx as transient only with bounded retries. After timeouts, re-read affected cases before replaying the full bulk update.\n\n### Error notes\n- 400 can indicate invalid status or malformed ID arrays.\n- Partial success behavior is not documented in the OpenAPI schema.\n- Avoid blind replay of a full bulk update after network timeouts.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Required array of QuickRCM prior authorization identifiers to update in the authenticated organization."},"status":{"type":"string","enum":["pending_submission","submitted","approved","denied","more_info_required","draft","in_review","partially_approved","expired","appealed","appeal_approved","appeal_denied","cancelled","voided"],"description":"Required target status from the prior authorization status enum."},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional shared status-transition reason, capped at 2000 characters."}},"required":["ids","status"]},"example":{"ids":["example-ids"],"status":"pending_submission","reason":"example-reason"}}},"description":"`ids` and `status` are required. `reason` is optional and capped at 2000 characters. Keep batches scoped and do not mix IDs from different tenants or workflows."},"responses":{"200":{"description":"Bulk status update result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"],"additionalProperties":{}}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/bulk/submit":{"post":{"operationId":"bulkSubmitPriorAuths","summary":"Queue prior authorization submissions","description":"Queues prior authorization submissions for asynchronous processing. The public OpenAPI description requires public callers to use `queueOnly: true`.\n\n### When to use\nUse this when multiple existing prior authorization cases are ready for the same submission workflow and the integration wants QuickRCM to queue asynchronous processing.\n\n### Before calling\nCollect trusted prior authorization IDs from the same tenant. Verify case readiness before queueing and use any `idempotencyKey` only as a non-PHI caller request marker.\n\n### Request guidance\n`ids` is required. `queueOnly` defaults to true and should remain true for public callers. `idempotencyKey` is optional and capped at 200 characters.\n\n### Request notes\n- `queueOnly: true` is required for public callers by the operation description.\n- `ids` should contain only tenant-owned prior authorization IDs.\n- Do not include PHI in `idempotencyKey`.\n\n### Response semantics\nHTTP 202 means the bulk submission request was queued. The current OpenAPI schema exposes `data` as a generic object and does not declare per-ID task IDs or external submission receipts.\n\n### Response notes\n- 202 means queued, not payer acceptance.\n- The response schema does not expose task IDs or per-case results.\n- External workflow completion must be observed later through local case or task evidence.\n\n### Errors and retries\nTreat 503 as submission queue unavailable, 429 as a backoff signal, 400 as invalid request shape, and 401/403 as credential or tenant failures. If a 202 response is lost, re-check local queue or case state before retrying; OpenAPI does not define idempotency-based deduplication semantics.\n\n### Error notes\n- 503 is declared for queue unavailability.\n- Do not retry with `queueOnly: false` for public API calls.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Required array of QuickRCM prior authorization identifiers selected for queued submission."},"queueOnly":{"type":"boolean","default":true,"description":"Boolean public side-effect control. For this endpoint, public callers must use true."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller-provided request marker capped at 200 characters. Keep it free of PHI and do not document it as a server-side deduplication guarantee."}},"required":["ids"]},"example":{"ids":["example-ids"],"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`ids` is required. `queueOnly` defaults to true and should remain true for public callers. `idempotencyKey` is optional and capped at 200 characters."},"responses":{"202":{"description":"Bulk prior authorization submissions queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"],"additionalProperties":{}}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}},"503":{"description":"Async queue is not configured for this public workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":503}}}}}}},"/api/v1/prior-auth/batches":{"post":{"operationId":"createPriorAuthBatch","summary":"Queue prior authorization bulk upload","description":"Creates a bulk upload processing batch for an already-uploaded prior authorization file. The public OpenAPI description requires public callers to use `queueOnly: true`.\n\n### When to use\nUse this after a prior authorization bulk-upload file is already stored and ready for QuickRCM asynchronous processing.\n\n### Before calling\nUpload the file through the approved storage workflow first, then provide the display `fileName`, storage `s3Key`, and `totalRows`. Keep object keys and upload paths out of logs.\n\n### Request guidance\n`fileName`, `s3Key`, and `totalRows` are required. `totalRows` is capped at 10000. `queueOnly` defaults to true and should remain true for public callers. `checkAuthRequired` controls whether requirement checks should be included when processing the batch. `idempotencyKey` is optional, capped at 200 characters, and should be treated as a caller request marker rather than a documented deduplication guarantee.\n\n### Request notes\n- `s3Key` is sensitive storage routing data; do not show real keys in examples or logs.\n- `totalRows` cannot exceed 10000.\n- `queueOnly: true` is required for public callers by the operation description.\n- `idempotencyKey` should be free of PHI and should not be described as proof of server-side deduplication.\n\n### Response semantics\nHTTP 202 means bulk upload processing was queued. The current OpenAPI response declares `data` as a generic object and does not expose a documented `batchId` field in the create response.\n\n### Response notes\n- 202 means queued for local processing.\n- The schema does not document a batch identifier in the response body.\n- Use getPriorAuthBatch only when a trusted workflow has provided a `batchId`.\n\n### Errors and retries\nTreat 400 as invalid file metadata or row count, 401/403 as credential or tenant failures, 429 as a backoff signal, and 5xx as transient or queue-related only with bounded retries. Reconcile batch state before retrying if a 202 response is lost.\n\n### Error notes\n- 400 can indicate unsupported metadata or too many rows.\n- After a lost 202 response, reconcile local batch or queue state before submitting another batch request.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Required display name for the already-uploaded batch file. Avoid embedding PHI in file names."},"s3Key":{"type":"string","minLength":1,"maxLength":1024,"description":"Required storage object key for the already-uploaded batch file. Treat as sensitive and do not expose real keys in docs or logs."},"totalRows":{"type":"integer","exclusiveMinimum":0,"maximum":10000,"description":"Required number of rows in the batch file, capped at 10000."},"queueOnly":{"type":"boolean","default":true,"description":"Boolean public side-effect control. For this endpoint, public callers must use true."},"checkAuthRequired":{"type":"boolean","description":"Optional flag indicating whether processing should include prior-auth requirement checks."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller-provided request marker capped at 200 characters. Keep it free of PHI; OpenAPI does not define deduplication semantics for it."}},"required":["fileName","s3Key","totalRows"]},"example":{"fileName":"Example prior_auth_batch","s3Key":"example-s3key","totalRows":1,"queueOnly":true,"checkAuthRequired":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`fileName`, `s3Key`, and `totalRows` are required. `totalRows` is capped at 10000. `queueOnly` defaults to true and should remain true for public callers. `checkAuthRequired` controls whether requirement checks should be included when processing the batch. `idempotencyKey` is optional, capped at 200 characters, and should be treated as a caller request marker rather than a documented deduplication guarantee."},"responses":{"202":{"description":"Bulk upload processing queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"],"additionalProperties":{}}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/batches/{batchId}":{"get":{"operationId":"getPriorAuthBatch","summary":"Get prior authorization batch status","description":"Returns status for one prior authorization bulk upload batch in the authenticated organization.\n\n### When to use\nUse this to poll or inspect a known batch after a trusted QuickRCM workflow has provided the `batchId`.\n\n### Before calling\nUse a `batchId` from the same tenant context. Avoid tight polling; use backoff or scheduled checks.\n\n### Request guidance\nPass `batchId` in the path. No request body or query parameters are declared.\n\n### Request notes\n- `batchId` is a QuickRCM batch identifier.\n- Do not guess batch IDs across tenants.\n- Use scheduled polling rather than tight loops.\n\n### Response semantics\nHTTP 200 returns bulk upload batch status in a generic `data` object according to the current schema. Public docs should avoid promising field names such as row counts, failure arrays, or result URLs unless the OpenAPI schema exposes them.\n\n### Response notes\n- The current schema declares `data` as an object without named properties.\n- Do not document row-level details unless the schema is expanded.\n- `meta.organizationId` echoes tenant context.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant batch context, 429 as a backoff signal, 400 as an invalid batch identifier, and 5xx as transient only with bounded retries.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant batches.\n- 429 should be retried with backoff.\n- 401 and 403 require credential or permission correction.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"batchId","in":"path","description":"QuickRCM prior authorization bulk upload batch identifier in the path."}],"responses":{"200":{"description":"Bulk upload batch status.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"],"additionalProperties":{}}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Batch not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/{priorAuthId}/documents":{"post":{"operationId":"uploadPriorAuthDocument","summary":"Create prior authorization document upload","description":"Creates a local prior authorization document record and returns a scoped presigned upload URL.\n\n### When to use\nUse this when a prior authorization case needs a supporting document uploaded before document-submission validation or later payer workflow processing.\n\n### Before calling\nConfirm the prior authorization belongs to the API key organization. Prepare file metadata only: name, MIME type or file type, and size in bytes.\n\n### Request guidance\n`fileName`, `fileType`, and `fileSize` are required. `fileSize` is capped at 52428800 bytes. Do not send file bytes to this endpoint; use the returned upload URL according to storage instructions.\n\n### Request notes\n- `fileSize` is capped at 50 MiB.\n- Use specific MIME types such as `application/pdf` when possible.\n- Do not include patient names or member IDs in file names unless operationally required.\n\n### Response semantics\nHTTP 202 returns `data.document` plus `data.uploadUrl`. The document is a local metadata record and the upload URL is sensitive, scoped upload setup. This response is not document submission or payer receipt.\n\n### Response notes\n- `uploadUrl` should be treated as a secret and not logged.\n- `data.document.status` is local document state.\n- Uploading bytes and validating submission are separate steps.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant prior authorization context, 400 as invalid file metadata, 429 as a backoff signal, and 5xx as transient only with bounded retries. If upload setup times out, check whether a document record was created before creating another one.\n\n### Error notes\n- 404 means the prior authorization was not found in the authenticated organization.\n- 400 can indicate unsupported or oversized file metadata.\n- Presigned upload URLs should be replaced after expiration rather than reused.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"priorAuthId","in":"path","description":"QuickRCM prior authorization case identifier in the path. It must resolve inside the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Required display file name for the supporting document. Avoid unnecessary PHI in names."},"fileType":{"type":"string","minLength":1,"maxLength":120,"description":"Required MIME type or file classification for the document."},"fileSize":{"type":"integer","exclusiveMinimum":0,"maximum":52428800,"description":"Required file size in bytes, capped at 52428800."}},"required":["fileName","fileType","fileSize"]},"example":{"fileName":"Example upload_prior_auth_document","fileType":"example-filetype","fileSize":1}}},"description":"`fileName`, `fileType`, and `fileSize` are required. `fileSize` is capped at 52428800 bytes. Do not send file bytes to this endpoint; use the returned upload URL according to storage instructions."},"responses":{"202":{"description":"Document upload URL accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"priorAuthId":{"type":["string","null"]},"filename":{"type":["string","null"]},"mimeType":{"type":["string","null"]},"sizeBytes":{"type":["integer","null"]},"documentType":{"type":["string","null"]},"status":{"type":["string","null"]},"availityId":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","priorAuthId","filename","mimeType","sizeBytes","documentType","status","availityId","createdAt","updatedAt"]},"uploadUrl":{"type":"string"}},"required":["document","uploadUrl"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"],"additionalProperties":{}}},"required":["success","data","meta"]},"example":{"success":true,"data":{"document":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","priorAuthId":"00000000-0000-4000-8000-000000000001","filename":"Example upload_prior_auth_document","mimeType":"example-mimetype","sizeBytes":1,"documentType":"example-documenttype","status":"active","availityId":"00000000-0000-4000-8000-000000000001","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"},"uploadUrl":"https://example.quickintell.com/resource"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prior authorization not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/authorizations/{priorAuthId}/documents/{documentId}/submit":{"post":{"operationId":"submitPriorAuthDocument","summary":"Validate prior authorization document submission","description":"Validates a prior authorization document submission request with organization-scoped local reads. The public OpenAPI description requires `dryRun: true`; vendor submission is skipped.\n\n### When to use\nUse this after upload setup and any required upload step when an integration needs QuickRCM to validate document submission readiness without live vendor submission.\n\n### Before calling\nConfirm both the prior authorization and document IDs belong to the same tenant and relationship. Keep `dryRun` true for public API calls.\n\n### Request guidance\n`dryRun` defaults to true and must be true for public callers. `attachmentTypeCode` is optional and capped at 10 characters. `idempotencyKey` is optional and capped at 200 characters.\n\n### Request notes\n- `dryRun: true` is required for public callers by the operation description.\n- `attachmentTypeCode` should be a short payer/document attachment code when needed.\n- The request validates local context; it does not upload file bytes.\n\n### Response semantics\nHTTP 202 means the document submission request was validated locally. The current OpenAPI response declares `data` as a generic object and does not include vendor receipt, attachment control number, or submission ID fields.\n\n### Response notes\n- 202 means local validation accepted.\n- The response does not prove payer receipt.\n- No raw vendor payload is returned.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant prior authorization/document context, 400 as invalid mode or attachment type, 429 as a backoff signal, and 5xx as transient only with bounded retries. Do not retry with `dryRun: false` for public API calls.\n\n### Error notes\n- 404 can mean the document does not belong to the specified prior authorization.\n- Do not document live vendor submission for this public endpoint.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"priorAuthId","in":"path","description":"QuickRCM prior authorization case identifier in the path. It must resolve inside the authenticated organization."},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path","description":"QuickRCM prior authorization document identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":true,"description":"Boolean validation mode. For this endpoint, public callers must use true."},"attachmentTypeCode":{"type":"string","minLength":1,"maxLength":10,"description":"Optional short attachment type code, capped at 10 characters."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller-provided request marker capped at 200 characters and free of PHI. Do not document it as a deduplication guarantee."}}},"example":{"dryRun":true,"attachmentTypeCode":"example-attachmenttypecode","idempotencyKey":"example-idempotencykey"}}},"description":"`dryRun` defaults to true and must be true for public callers. `attachmentTypeCode` is optional and capped at 10 characters. `idempotencyKey` is optional and capped at 200 characters."},"responses":{"202":{"description":"Document submission request validated locally.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"],"additionalProperties":{}}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Prior authorization or document not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/prior-auth/documents/bulk/submit":{"post":{"operationId":"bulkSubmitPriorAuthDocuments","summary":"Validate bulk prior authorization document submissions","description":"Validates bulk prior authorization document submission requests with organization-scoped local reads. The public OpenAPI description requires `dryRun: true`; vendor submission is skipped.\n\n### When to use\nUse this when multiple prior authorization document workflows need local validation before any external document submission capability is enabled.\n\n### Before calling\nBuild `priorAuthIds` from trusted case IDs in the same tenant and confirm their supporting documents are prepared in QuickRCM. Keep `dryRun` true for public API calls.\n\n### Request guidance\n`priorAuthIds` is required. `dryRun` defaults to true and must remain true for public callers. Optional `attachmentTypeCode` is capped at 10 characters, and optional `idempotencyKey` is capped at 200 characters.\n\n### Request notes\n- `priorAuthIds` is an array of QuickRCM prior authorization identifiers.\n- `dryRun: true` is required for public callers by the operation description.\n- No document bytes or upload URLs should be sent in this request.\n\n### Response semantics\nHTTP 202 means the bulk document submission request was validated locally. The current OpenAPI response declares `data` as a generic object and does not expose per-case results or vendor receipt details.\n\n### Response notes\n- 202 means local validation accepted.\n- The schema does not declare per-ID validation results.\n- Vendor submission is skipped.\n\n### Errors and retries\nTreat 400 as invalid ID array or dry-run controls, 401/403 as credential or tenant failures, 429 as a backoff signal, and 5xx as transient only with bounded retries. Re-check local state before retrying a bulk validation request after a lost response.\n\n### Error notes\n- 400 can indicate malformed IDs or invalid mode fields.\n- Do not document live bulk vendor submission for this public endpoint.\n","tags":["Prior Authorization"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"priorAuthIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Required array of QuickRCM prior authorization identifiers selected for bulk document submission validation."},"dryRun":{"type":"boolean","default":true,"description":"Boolean validation mode. For this endpoint, public callers must use true."},"attachmentTypeCode":{"type":"string","minLength":1,"maxLength":10,"description":"Optional short attachment type code to apply to the bulk validation request."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller-provided request marker capped at 200 characters and free of PHI. Do not document it as a deduplication guarantee."}},"required":["priorAuthIds"]},"example":{"priorAuthIds":["example-priorauthids"],"dryRun":true,"attachmentTypeCode":"example-attachmenttypecode","idempotencyKey":"example-idempotencykey"}}},"description":"`priorAuthIds` is required. `dryRun` defaults to true and must remain true for public callers. Optional `attachmentTypeCode` is capped at 10 characters, and optional `idempotencyKey` is capped at 200 characters."},"responses":{"202":{"description":"Bulk document submission request validated locally.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"],"additionalProperties":{}}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/reports/catalog":{"get":{"operationId":"listReportsCatalog","summary":"List report catalog","description":"Lists report definitions available to the organization selected by the bearer API key, including report category, availability, supported filters, and metric identifiers.\n\n### When to use\nUse this endpoint to populate report-picker UI, decide which public report definitions an integration can show, or filter the catalog by category or availability before calling a report-specific endpoint.\n\n### Before calling\nAuthenticate with an API key accepted for Reports public API reads, such as one with `reports:read` or `reports:write`. Decide whether to request all catalog entries or narrow the response with `category` and `availability` query parameters.\n\n### Request guidance\nSend query parameters only. `category` must be one of `FINANCIAL`, `CLAIMS`, `DENIALS`, or `OPERATIONS`. `availability` must be `AVAILABLE` or `PLANNED`. The endpoint does not declare a request body and does not accept a tenant selector.\n\n### Request notes\n- The API key selects the organization; do not include `organizationId` or `orgId`.\n- Use `availability=AVAILABLE` when a client only wants report definitions that are currently published as public report surfaces.\n- Use `availability=PLANNED` only for roadmap/catalog display, not as proof that a report can be executed.\n\n### Response semantics\nHTTP 200 returns `success`, `data.reports`, `data.total`, and `meta.organizationId`. Each report entry includes `id`, `name`, `category`, `availability`, `description`, `supportedFilters`, and `metrics`. Catalog `metrics` are stable metric identifier strings, not metric values.\n\n### Response notes\n- `data.total` is the number of catalog entries after the supplied filters are applied.\n- `supportedFilters` currently uses public filter identifiers such as `dateRange` and `facilityId`.\n- `meta.organizationId` echoes authenticated tenant context and should not be used to infer cross-tenant visibility.\n\n### Errors and retries\nTreat 400 as an invalid query enum or request shape, 401 as missing or invalid authentication, 403 as missing or insufficient Reports/public API scope, 429 as rate limiting, and 5xx as potentially transient. Because this is read-only catalog discovery, retry 429 or transient 5xx responses with bounded backoff.\n\n### Error notes\n- 400 can result from unsupported `category` or `availability` values.\n- 403 means the credential was not accepted for this Reports public API endpoint.\n- Retry 429 with normal rate-limit backoff instead of polling tightly.\n","tags":["Reports"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["FINANCIAL","CLAIMS","DENIALS","OPERATIONS"]},"required":false,"name":"category","in":"query","description":"Optional catalog filter and report classification. Public values are `FINANCIAL`, `CLAIMS`, `DENIALS`, and `OPERATIONS`."},{"schema":{"type":"string","enum":["AVAILABLE","PLANNED"]},"required":false,"name":"availability","in":"query","description":"Optional catalog filter and catalog entry status. `AVAILABLE` means the report is published in the public catalog; `PLANNED` means roadmap/catalog metadata only."}],"responses":{"200":{"description":"Report definitions for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"reports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","enum":["FINANCIAL","CLAIMS","DENIALS","OPERATIONS"]},"availability":{"type":"string","enum":["AVAILABLE","PLANNED"]},"description":{"type":"string"},"supportedFilters":{"type":"array","items":{"type":"string","enum":["dateRange","facilityId"]}},"metrics":{"type":"array","items":{"type":"string"}}},"required":["id","name","category","availability","description","supportedFilters","metrics"]}},"total":{"type":"integer","minimum":0}},"required":["reports","total"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"reports":[{"id":"00000000-0000-4000-8000-000000000001","name":"Example reports_catalog","category":"FINANCIAL","availability":"AVAILABLE","description":"Example reports_catalog note","supportedFilters":["dateRange"],"metrics":["example-metrics"]}],"total":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"API key is missing or has insufficient reports/public API scope for this endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/reports/summary":{"get":{"operationId":"getReportsSummary","summary":"Get reports summary","description":"Returns the `revenue-cycle-summary` report for the authenticated organization, with aggregate claim and denial counts by status plus decimal-string money totals.\n\n### When to use\nUse this endpoint for lightweight organization-level revenue-cycle dashboards, integration health checks, or reporting snapshots that need aggregate claim and denial metrics without exporting patient, payer, EDI, or clinical-note detail.\n\n### Before calling\nAuthenticate with an API key accepted for Reports public API reads, such as one with `reports:read` or `reports:write`. Choose explicit UTC date bounds when a client needs a repeatable reporting period, and send `facilityId` only when the client needs to narrow metrics to one facility in the authenticated organization.\n\n### Request guidance\nSend optional query parameters only. `startDate` and `endDate` are ISO 8601 date-time strings; when both are supplied, `startDate` must be before or equal to `endDate`. `facilityId` is an optional non-empty string. The endpoint does not declare a request body and does not accept a tenant selector.\n\n### Request notes\n- The API key selects the organization; do not include `organizationId` or `orgId`.\n- If date filters are omitted, the response period fields are `null`; the public contract does not promise a default reporting window.\n- The OpenAPI contract does not declare a 404 response for an unknown `facilityId`; clients should treat facility validation as tenant-scoped input validation rather than resource retrieval.\n\n### Response semantics\nHTTP 200 returns `success`, `data`, and `meta`. `data.reportId` is fixed to `revenue-cycle-summary`; `period` and `filters` echo the effective filters; `metrics.claims` and `metrics.denials` contain aggregate status-count maps and decimal-string money fields. Status-map keys are local status labels and are not fixed by the OpenAPI schema.\n\n### Response notes\n- `reportId` is currently always `revenue-cycle-summary`.\n- `claims.total` and `denials.total` are aggregate counts derived from returned status-count maps.\n- `totalCharges`, `totalPaid`, `patientBalance`, `deniedAmount`, and `paidAmount` are serialized as decimal strings, not JSON numbers.\n- The response intentionally omits patient names, member IDs, payer payloads, raw EDI, raw EHR responses, transcripts, and clinical-note text.\n\n### Errors and retries\nTreat 400 as invalid query shape, invalid date-time, or invalid date ordering; 401 as missing or invalid authentication; 403 as missing or insufficient Reports/public API scope; 429 as rate limiting; and 5xx as potentially transient. Correct 400/401/403 before retrying, and use bounded backoff for 429 or transient 5xx.\n\n### Error notes\n- 400 can include invalid ISO date-time values or `startDate` later than `endDate`.\n- 403 indicates the API key is authenticated but not accepted for this Reports public API endpoint.\n- Retry 429 with backoff instead of repeated immediate polling.\n","tags":["Reports"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Inclusive UTC start of the reporting period."},"required":false,"description":"Optional inclusive UTC start of the reporting period, supplied as an ISO 8601 date-time query parameter.","name":"startDate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive UTC end of the reporting period."},"required":false,"description":"Optional inclusive UTC end of the reporting period, supplied as an ISO 8601 date-time query parameter. When paired with `startDate`, it must be greater than or equal to `startDate`.","name":"endDate","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Optional facility filter scoped inside the authenticated organization."},"required":false,"description":"Optional facility filter applied inside the authenticated organization context.","name":"facilityId","in":"query"}],"responses":{"200":{"description":"Organization-scoped revenue-cycle summary metrics.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"reportId":{"type":"string","enum":["revenue-cycle-summary"]},"organizationId":{"type":"string"},"period":{"type":"object","properties":{"startDate":{"type":["string","null"],"format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"}},"required":["startDate","endDate"]},"filters":{"type":"object","properties":{"facilityId":{"type":["string","null"]}},"required":["facilityId"]},"metrics":{"type":"object","properties":{"claims":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"byStatus":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"totalCharges":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"},"totalPaid":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"},"patientBalance":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"}},"required":["total","byStatus","totalCharges","totalPaid","patientBalance"]},"denials":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"byStatus":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"deniedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"},"paidAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","example":"125.50"}},"required":["total","byStatus","deniedAmount","paidAmount"]}},"required":["claims","denials"]}},"required":["reportId","organizationId","period","filters","metrics"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"reportId":"revenue-cycle-summary","organizationId":"00000000-0000-4000-8000-000000000001","period":{"startDate":"2026-06-08T10:15:30Z","endDate":"2026-06-08T10:15:30Z"},"filters":{"facilityId":"00000000-0000-4000-8000-000000000001"},"metrics":{"claims":{"total":1,"byStatus":{},"totalCharges":"125.50","totalPaid":"125.50","patientBalance":"125.50"},"denials":{"total":1,"byStatus":{},"deniedAmount":"125.50","paidAmount":"125.50"}}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"API key is missing or has insufficient reports/public API scope for this endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/dashboard":{"get":{"operationId":"getRevenueIntegrityDashboard","summary":"Get revenue integrity dashboard metrics","description":"Returns organization-scoped Revenue Integrity dashboard metrics grouped by charge reconciliation, coding validation, underpayment recovery, overall revenue at risk, and recovered revenue.\n\n### When to use\nUse this endpoint to power executive or operational dashboards after Revenue Integrity records already exist in QuickRCM.\n\n### Before calling\nAuthenticate with a tenant-scoped API key that has `revenue-integrity:read` or `revenue-integrity:write`. The OpenAPI contract does not expose request filters for this endpoint.\n\n### Request guidance\nDo not send organization selectors, patient identifiers, payer payloads, or date filters. The request has no documented query parameters beyond an empty query schema.\n\n### Request notes\n- The API key selects the organization; there is no public `organizationId` query parameter.\n- The endpoint has no date-range filter in the OpenAPI contract.\n- Use dashboard responses as local operational metrics, not payer adjudication evidence.\n\n### Response semantics\nHTTP 200 returns local aggregate metrics calculated from organization-owned charge reconciliation, charge lag, coding validation, Diagnosis-Related Group (DRG) / Present on Admission (POA) validation, and underpayment case records. Monetary values are decimal strings. `chargeCaptureRate` and `recoveryRate` are percentage-like numbers computed from local records.\n\n### Response notes\n- `data.chargeReconciliation` includes local session counts, active discrepancy count, missing charge count, leakage estimate, latest average charge lag, and charge capture rate.\n- `data.codingValidation` includes local validation counts, optimization opportunities, estimated coding impact, and Present on Admission issue count.\n- `data.underpaymentRecovery` includes open case count, identified/recovered amount totals, recovery rate, pending appeals, and average recovery days.\n\n### Errors and retries\nTreat 401 and 403 as credential, scope, or tenant authorization issues. Treat 429 as a backoff signal because the module public API limit is 60 requests per minute. Retry transient 5xx responses with bounded retries.\n\n### Error notes\n- 429 should be handled with scheduled refresh or exponential backoff.\n- 401 and 403 require credential or scope correction before retrying.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Revenue integrity dashboard metrics for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"chargeReconciliation":{"type":"object","properties":{"totalSessions":{"type":"integer","minimum":0},"activeAlerts":{"type":"integer","minimum":0},"missingChargesCount":{"type":"integer","minimum":0},"estimatedLeakage":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"avgChargeLagDays":{"type":"number"},"chargeCaptureRate":{"type":"number"}},"required":["totalSessions","activeAlerts","missingChargesCount","estimatedLeakage","avgChargeLagDays","chargeCaptureRate"]},"codingValidation":{"type":"object","properties":{"totalValidations":{"type":"integer","minimum":0},"failedValidations":{"type":"integer","minimum":0},"warningValidations":{"type":"integer","minimum":0},"drgOptimizationOpportunities":{"type":"integer","minimum":0},"estimatedCodingImpact":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"poaIssuesCount":{"type":"integer","minimum":0}},"required":["totalValidations","failedValidations","warningValidations","drgOptimizationOpportunities","estimatedCodingImpact","poaIssuesCount"]},"underpaymentRecovery":{"type":"object","properties":{"totalOpenCases":{"type":"integer","minimum":0},"totalIdentifiedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"totalRecoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"recoveryRate":{"type":"number"},"pendingAppeals":{"type":"integer","minimum":0},"avgRecoveryDays":{"type":"integer","minimum":0}},"required":["totalOpenCases","totalIdentifiedAmount","totalRecoveredAmount","recoveryRate","pendingAppeals","avgRecoveryDays"]},"overallRevenueAtRisk":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"overallRecoveredRevenue":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["chargeReconciliation","codingValidation","underpaymentRecovery","overallRevenueAtRisk","overallRecoveredRevenue"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"chargeReconciliation":{"totalSessions":1,"activeAlerts":1,"missingChargesCount":1,"estimatedLeakage":"example-estimatedleakage","avgChargeLagDays":125.5,"chargeCaptureRate":125.5},"codingValidation":{"totalValidations":1,"failedValidations":1,"warningValidations":1,"drgOptimizationOpportunities":1,"estimatedCodingImpact":"example-estimatedcodingimpact","poaIssuesCount":1},"underpaymentRecovery":{"totalOpenCases":1,"totalIdentifiedAmount":"example-totalidentifiedamount","totalRecoveredAmount":"example-totalrecoveredamount","recoveryRate":1.25,"pendingAppeals":1,"avgRecoveryDays":1},"overallRevenueAtRisk":"example-overallrevenueatrisk","overallRecoveredRevenue":"example-overallrecoveredrevenue"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/underpayment-cases":{"get":{"operationId":"listRevenueIntegrityUnderpaymentCases","summary":"List underpayment cases","description":"Lists organization-owned underpayment recovery cases with optional filters for status, underpayment type, payer configuration, assignee, and page-based pagination.\n\n### When to use\nUse this endpoint to build underpayment worklists, appeal queues, recovery dashboards, or reconciliation views before updating appeal or recovery state.\n\n### Before calling\nAuthenticate with Revenue Integrity read access. If filtering by `payerConfigId` or `assignedToId`, use identifiers from the same API-key organization.\n\n### Request guidance\n`page` defaults to 1. `pageSize` defaults to 25 and is capped at 100. `status` and `underpaymentType` must match the public Revenue Integrity enums. Do not send Protected Health Information or free-text search terms; no search parameter is exposed.\n\n### Request notes\n- `status` values include IDENTIFIED, UNDER_REVIEW, CONFIRMED, APPEAL_DRAFTED, APPEAL_SUBMITTED, RECOVERED, CLOSED_NO_RECOVERY, CLOSED_WRITE_OFF, and BATCHED.\n- `underpaymentType` values include CONTRACT_VARIANCE, STOP_LOSS, OUTLIER, IMPLANT_COST, CARVE_OUT, SEQUESTRATION, INTEREST, and OTHER.\n- There is no public `claimId` or free-text search filter in this endpoint.\n\n### Response semantics\nHTTP 200 returns `data.underpaymentCases`, total count, current page, page size, total pages, and `meta.organizationId`. Rows include local financial strings, appeal metadata, nested claim/payer/contract/assignee references, and activity count.\n\n### Response notes\n- Amounts such as `billedAmount`, `expectedAmount`, `paidAmount`, `varianceAmount`, `recoveredAmount`, and `interestAmount` are decimal strings.\n- `claim`, `payer`, `contract`, and `assignedTo` are limited references and can be null.\n- The list is local QuickRCM recovery state, not a payer remittance, Electronic Remittance Advice feed, or appeal decision feed.\n\n### Errors and retries\nCorrect invalid enum or pagination values before retrying. Treat 401/403 as credential or scope issues and 429 as a backoff signal.\n\n### Error notes\n- 400 can indicate invalid page, pageSize, status, or underpaymentType.\n- A valid but empty filtered result returns an empty array rather than an error.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query","description":"One-based page number. Defaults to 1."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"Number of underpayment cases per page. Defaults to 25 and cannot exceed 100."},{"schema":{"type":"string","enum":["IDENTIFIED","UNDER_REVIEW","CONFIRMED","APPEAL_DRAFTED","APPEAL_SUBMITTED","RECOVERED","CLOSED_NO_RECOVERY","CLOSED_WRITE_OFF","BATCHED"]},"required":false,"name":"status","in":"query","description":"Workflow status filter or target status. Valid values depend on the endpoint schema and module state machine."},{"schema":{"type":"string","enum":["CONTRACT_VARIANCE","STOP_LOSS","OUTLIER","IMPLANT_COST","CARVE_OUT","SEQUESTRATION","INTEREST","OTHER"]},"required":false,"name":"underpaymentType","in":"query","description":"Local underpayment case classification. Public detection-created cases use CONTRACT_VARIANCE in the current handler."},{"schema":{"type":"string","minLength":1},"required":false,"name":"payerConfigId","in":"query","description":"Optional organization-scoped payer configuration filter."},{"schema":{"type":"string","minLength":1},"required":false,"name":"assignedToId","in":"query","description":"Optional QuickRCM user identifier used to filter assigned underpayment cases."}],"responses":{"200":{"description":"Underpayment recovery cases for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"underpaymentCases":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"claimId":{"type":"string"},"remittanceClaimId":{"type":["string","null"]},"paymentId":{"type":["string","null"]},"contractId":{"type":["string","null"]},"payerConfigId":{"type":["string","null"]},"caseNumber":{"type":"string"},"underpaymentType":{"type":"string","enum":["CONTRACT_VARIANCE","STOP_LOSS","OUTLIER","IMPLANT_COST","CARVE_OUT","SEQUESTRATION","INTEREST","OTHER"]},"status":{"type":"string","enum":["IDENTIFIED","UNDER_REVIEW","CONFIRMED","APPEAL_DRAFTED","APPEAL_SUBMITTED","RECOVERED","CLOSED_NO_RECOVERY","CLOSED_WRITE_OFF","BATCHED"]},"billedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"expectedAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"paidAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"varianceAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"recoveredAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"interestAmount":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"priorityScore":{"type":["number","null"]},"appealDeadline":{"type":["string","null"],"format":"date-time"},"appealSubmittedAt":{"type":["string","null"],"format":"date-time"},"appealReference":{"type":["string","null"]},"appealLevel":{"type":["string","null"]},"identifiedAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"autoDetected":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"claim":{"type":["object","null"],"properties":{"id":{"type":"string"},"claimControlNumber":{"type":["string","null"]}},"required":["id","claimControlNumber"]},"payer":{"type":["object","null"],"properties":{"id":{"type":"string"},"payerName":{"type":"string"}},"required":["id","payerName"]},"contract":{"type":["object","null"],"properties":{"id":{"type":"string"},"contractName":{"type":"string"}},"required":["id","contractName"]},"assignedTo":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"activityCount":{"type":"integer","minimum":0}},"required":["id","organizationId","claimId","remittanceClaimId","paymentId","contractId","payerConfigId","caseNumber","underpaymentType","status","billedAmount","expectedAmount","paidAmount","varianceAmount","recoveredAmount","interestAmount","priorityScore","appealDeadline","appealSubmittedAt","appealReference","appealLevel","identifiedAt","resolvedAt","autoDetected","createdAt","updatedAt","claim","payer","contract","assignedTo","activityCount"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1},"totalPages":{"type":"integer","minimum":0}},"required":["underpaymentCases","total","page","pageSize","totalPages"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"underpaymentCases":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","remittanceClaimId":"00000000-0000-4000-8000-000000000001","paymentId":"00000000-0000-4000-8000-000000000001","contractId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","caseNumber":"example-casenumber","underpaymentType":"CONTRACT_VARIANCE","status":"IDENTIFIED","billedAmount":"example-billedamount","expectedAmount":"example-expectedamount","paidAmount":"example-paidamount","varianceAmount":"example-varianceamount","recoveredAmount":"example-recoveredamount","interestAmount":"example-interestamount","priorityScore":1.25,"appealDeadline":"2026-06-08T10:15:30Z","appealSubmittedAt":"2026-06-08T10:15:30Z","appealReference":"example-appealreference","appealLevel":"example-appeallevel","identifiedAt":"2026-06-08T10:15:30Z","resolvedAt":"2026-06-08T10:15:30Z","autoDetected":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","claim":{"id":"00000000-0000-4000-8000-000000000001","claimControlNumber":"example-claimcontrolnumber"},"payer":{"id":"00000000-0000-4000-8000-000000000001","payerName":"Example revenue_integrity_underpayment_case"},"contract":{"id":"00000000-0000-4000-8000-000000000001","contractName":"Example revenue_integrity_underpayment_case"},"assignedTo":{"id":"00000000-0000-4000-8000-000000000001","name":"Example revenue_integrity_underpayment_case"},"activityCount":1}],"total":1,"page":1,"pageSize":1,"totalPages":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/charge-reconciliations":{"post":{"operationId":"createRevenueIntegrityChargeReconciliation","summary":"Create a charge reconciliation session","description":"Creates a local charge reconciliation session and explicit source procedure items after validating the facility and each patient belongs to the authenticated organization.\n\n### When to use\nUse this endpoint when an external scheduling, procedure, or charge-capture feed needs QuickRCM to compare performed procedures against local charge activity.\n\n### Before calling\nAuthenticate with `revenue-integrity:write`. Resolve `facilityId` and each `patientId` from QuickRCM for the same tenant. Prepare a bounded procedures array with minimum-necessary procedure context.\n\n### Request guidance\n`facilityId`, `dateRangeStart`, `dateRangeEnd`, and at least one procedure are required. `procedures` accepts 1 to 1000 entries. Each procedure requires `patientId`, `procedureDate`, and `procedureDesc`; `procedureCode`, `encounterId`, performing provider, room, source system, and source record id are optional.\n\n### Request notes\n- `dateRangeStart`, `dateRangeEnd`, and `procedureDate` must be ISO datetimes.\n- `departmentCode` and `departmentName` are optional labels for the reconciliation session and should identify the source department without embedding PHI.\n- Avoid embedding raw Electronic Health Record responses, operative transcripts, or payer payloads in source fields.\n\n### Response semantics\nHTTP 201 returns a local session id when available, status `IN_PROGRESS`, mode `created`, and `meta.organizationId`. Created items start as local pending reconciliation items. No claim correction, payer submission, or external charge posting occurs.\n\n### Response notes\n- `mode` is `created` on success.\n- The response does not include the created item list.\n- Downstream discrepancy resolution is handled by `resolveRevenueIntegrityChargeReconciliationItem`.\n\n### Errors and retries\nFix validation errors before retrying. A 404 can mean the facility or a patient did not resolve in the authenticated organization. The API accepts `idempotencyKey` but does not guarantee duplicate suppression, so check local sessions before recreating after a timeout.\n\n### Error notes\n- 404 can indicate wrong-tenant facility or patient identifiers.\n- Duplicate sessions are possible if a caller retries a timed-out request without checking local state.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"facilityId":{"type":"string","minLength":1,"description":"Required QuickRCM facility identifier scoped to the API-key organization."},"dateRangeStart":{"type":"string","format":"date-time","description":"Required ISO datetime lower bound for the reconciliation window."},"dateRangeEnd":{"type":"string","format":"date-time","description":"Required ISO datetime upper bound for the reconciliation window; it should be on or after `dateRangeStart`."},"departmentCode":{"type":"string","minLength":1,"maxLength":40,"description":"Optional department code, capped at 40 characters, used to label the local session."},"departmentName":{"type":"string","minLength":1,"maxLength":200,"description":"Optional department display name, capped at 200 characters, used to label the local session."},"procedures":{"type":"array","items":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"Required QuickRCM patient identifier for each procedure. It must belong to the same organization."},"encounterId":{"type":"string","minLength":1,"description":"Optional source encounter identifier for the procedure. Use the QuickRCM or source-system reference expected by the integration contract."},"procedureDate":{"type":"string","format":"date-time","description":"Required ISO datetime for when the procedure was performed."},"procedureCode":{"type":"string","minLength":1,"description":"Optional procedure code, such as Current Procedural Terminology (CPT), Healthcare Common Procedure Coding System (HCPCS), ICD-10-PCS, or a local code."},"procedureDesc":{"type":"string","minLength":1,"description":"Required procedure description for each source procedure. Keep it minimum necessary."},"performingProvider":{"type":"string","minLength":1,"description":"Optional provider display string from the source feed. Avoid unnecessary demographics."},"roomNumber":{"type":"string","minLength":1,"description":"Optional room or location label from the source feed."},"sourceSystem":{"type":"string","minLength":1,"description":"Optional source label for the procedure entry. Use a short integration name, not a raw payload."},"sourceRecordId":{"type":"string","minLength":1,"description":"Optional caller-side correlation identifier. Do not include raw vendor payloads, S3 keys, signed URLs, or secrets."}},"required":["patientId","procedureDate","procedureDesc"]},"minItems":1,"maxItems":1000,"description":"Array of performed procedure source entries used to seed local reconciliation items. Minimum 1, maximum 1000."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters. The public contract does not guarantee server-side duplicate suppression."}},"required":["facilityId","dateRangeStart","dateRangeEnd","procedures"]},"example":{"facilityId":"00000000-0000-4000-8000-000000000001","dateRangeStart":"2026-06-08T10:15:30Z","dateRangeEnd":"2026-06-08T10:15:30Z","procedures":[{"patientId":"00000000-0000-4000-8000-000000000001","procedureDate":"2026-06-08T10:15:30Z","procedureDesc":"example-proceduredesc","encounterId":"00000000-0000-4000-8000-000000000001","procedureCode":"example-procedurecode","performingProvider":"example-performingprovider","roomNumber":"example-roomnumber","sourceSystem":"example-sourcesystem","sourceRecordId":"00000000-0000-4000-8000-000000000001"}],"departmentCode":"example-departmentcode","departmentName":"Example revenue_integrity_charge_reconciliation","idempotencyKey":"example-idempotencykey"}}},"description":"`facilityId`, `dateRangeStart`, `dateRangeEnd`, and at least one procedure are required. `procedures` accepts 1 to 1000 entries. Each procedure requires `patientId`, `procedureDate`, and `procedureDesc`; `procedureCode`, `encounterId`, performing provider, room, source system, and source record id are optional."},"responses":{"201":{"description":"Charge reconciliation session created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/charge-reconciliations/{sessionId}/items/{itemId}/resolve":{"put":{"operationId":"resolveRevenueIntegrityChargeReconciliationItem","summary":"Resolve a charge reconciliation item","description":"Marks one organization-scoped charge reconciliation item as resolved with a resolution action and optional notes.\n\n### When to use\nUse this endpoint after staff or an integration has reviewed a missing charge, extra charge, variance, or pending reconciliation item and decided the local resolution outcome.\n\n### Before calling\nAuthenticate with write scope. Use a `sessionId` and `itemId` obtained from QuickRCM for the same tenant. Confirm the item is still in a resolvable local status.\n\n### Request guidance\nThe body requires `resolutionAction`: CHARGE_ADDED, CHARGE_CORRECTED, CHARGE_REMOVED, or NO_ACTION. `resolutionNotes` is optional and capped at 2000 characters.\n\n### Request notes\n- `sessionId` and `itemId` are both path selectors.\n- Only locally resolvable discrepancy or pending states should be resolved through this endpoint.\n- Keep `resolutionNotes` concise and free of raw clinical transcripts or payer payloads.\n\n### Response semantics\nHTTP 200 returns the item id, status `RESOLVED`, mode `updated`, and `meta.organizationId`. This records local resolution metadata; it does not add charges to claims, submit corrected claims, or mutate Electronic Health Record charge records.\n\n### Response notes\n- The response is local workflow state only.\n- `resolvedById` is derived from the public API actor internally and is not supplied by the caller.\n\n### Errors and retries\n404 means the item/session pair was missing or outside the organization. 400 can mean the item status is not resolvable. Re-read item state after a timeout before retrying to avoid overwriting another user's resolution.\n\n### Error notes\n- 400 can indicate the item has already moved beyond a resolvable status.\n- 404 can intentionally hide wrong-tenant items.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path","description":"Charge reconciliation session identifier from the path."},{"schema":{"type":"string","minLength":1},"required":true,"name":"itemId","in":"path","description":"Charge reconciliation item identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resolutionAction":{"type":"string","enum":["CHARGE_ADDED","CHARGE_CORRECTED","CHARGE_REMOVED","NO_ACTION"],"description":"Required local resolution action: CHARGE_ADDED, CHARGE_CORRECTED, CHARGE_REMOVED, or NO_ACTION."},"resolutionNotes":{"type":"string","maxLength":2000,"description":"Optional local resolution note capped at 2000 characters. Avoid PHI and raw payer or EHR payloads."}},"required":["resolutionAction"]},"example":{"resolutionAction":"CHARGE_ADDED","resolutionNotes":"Example revenue_integrity_charge_reconciliation_item note"}}},"description":"The body requires `resolutionAction`: CHARGE_ADDED, CHARGE_CORRECTED, CHARGE_REMOVED, or NO_ACTION. `resolutionNotes` is optional and capped at 2000 characters."},"responses":{"200":{"description":"Charge reconciliation item resolved.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/charge-lag-reports":{"post":{"operationId":"generateRevenueIntegrityChargeLagReport","summary":"Generate a charge lag report","description":"Creates a local charge lag report record for the requested period and optional facility.\n\n### When to use\nUse this endpoint to snapshot charge lag reporting inputs for operational monitoring or dashboard refreshes.\n\n### Before calling\nAuthenticate with write scope. If supplying `facilityId`, resolve it from the same organization.\n\n### Request guidance\n`periodStart` and `periodEnd` are required ISO datetimes. `facilityId` is optional. The API accepts `idempotencyKey` but does not guarantee duplicate suppression.\n\n### Request notes\n- `periodStart` and `periodEnd` must be ISO datetimes.\n- The endpoint does not expose department, payer, or provider filters.\n- Use a caller-side idempotency policy around repeated period snapshots.\n\n### Response semantics\nHTTP 201 returns a local report id when available, status `CREATED`, mode `created`, and `meta.organizationId`. The immediate response does not include detailed lag metrics.\n\n### Response notes\n- `status` is `CREATED` on success.\n- Dashboard lag metrics are read through `getRevenueIntegrityDashboard`.\n\n### Errors and retries\nFix invalid datetime or facility identifiers before retrying. After a timeout, check for an existing report covering the same period before creating another.\n\n### Error notes\n- 404 can indicate a supplied facility is not in the authenticated organization.\n- 400 can indicate malformed date-time input.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"facilityId":{"type":"string","minLength":1,"description":"Optional QuickRCM facility identifier scoped to the API key organization."},"periodStart":{"type":"string","format":"date-time","description":"Required ISO datetime lower bound for the charge lag reporting period."},"periodEnd":{"type":"string","format":"date-time","description":"Required ISO datetime upper bound for the charge lag reporting period."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters."}},"required":["periodStart","periodEnd"]},"example":{"periodStart":"2026-06-08T10:15:30Z","periodEnd":"2026-06-08T10:15:30Z","facilityId":"00000000-0000-4000-8000-000000000001","idempotencyKey":"example-idempotencykey"}}},"description":"`periodStart` and `periodEnd` are required ISO datetimes. `facilityId` is optional. The API accepts `idempotencyKey` but does not guarantee duplicate suppression."},"responses":{"201":{"description":"Charge lag report created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/charge-audits":{"post":{"operationId":"runRevenueIntegrityChargeAudit","summary":"Run a charge capture audit","description":"Creates a local charge capture audit record after validating supplied patient, claim, facility, and billing encounter references when present.\n\n### When to use\nUse this endpoint when an external charge-capture integration wants QuickRCM to track a specific service, procedure, expected amount, or suspected missed charge for review.\n\n### Before calling\nAuthenticate with write scope. Resolve required `patientId` and any optional claim, facility, or billing encounter identifiers from the same tenant.\n\n### Request guidance\n`patientId`, `procedureCode`, and `serviceDate` are required. `units` defaults to 1 and must be a positive integer. `expectedAmount` can be a number or decimal string. `procedureDesc`, `encounterId`, `claimId`, and `facilityId` are optional.\n\n### Request notes\n- `serviceDate` must be an ISO datetime.\n- `expectedAmount` should preserve decimal precision and must be a finite number or decimal string.\n- Do not use `procedureDesc` to store raw clinical notes or transcripts.\n\n### Response semantics\nHTTP 201 returns a local audit id, status `OPEN`, mode `created`, and `meta.organizationId`. It is local audit tracking only and does not alter claim lines or Electronic Health Record charge records.\n\n### Response notes\n- `mode` is `created` on success.\n- The response does not include generated audit findings.\n\n### Errors and retries\nA 404 can indicate a referenced patient, claim, facility, or billing encounter is unavailable in the tenant context. If a network timeout occurs, search local audits before retrying because the public contract does not guarantee idempotent replay.\n\n### Error notes\n- 400 can indicate invalid money amount, datetime, or units.\n- 404 can indicate wrong-tenant references.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"Required QuickRCM patient identifier scoped to the API-key organization."},"encounterId":{"type":"string","minLength":1,"description":"Optional billing encounter identifier scoped to the same organization."},"claimId":{"type":"string","minLength":1,"description":"Optional QuickRCM claim identifier scoped to the same organization."},"facilityId":{"type":"string","minLength":1,"description":"Optional QuickRCM facility identifier scoped to the same organization."},"procedureCode":{"type":"string","minLength":1,"description":"Required Current Procedural Terminology, Healthcare Common Procedure Coding System, ICD-10-PCS, or local procedure code being audited."},"procedureDesc":{"type":"string","minLength":1,"description":"Optional minimum-necessary procedure description."},"serviceDate":{"type":"string","format":"date-time","description":"Required ISO datetime for the audited service."},"units":{"type":"integer","minimum":1,"default":1,"description":"Positive integer service units. Defaults to 1."},"expectedAmount":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional expected charge amount as a number or decimal string."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."}},"required":["patientId","procedureCode","serviceDate"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","procedureCode":"example-procedurecode","serviceDate":"2026-06-08T10:15:30Z","encounterId":"00000000-0000-4000-8000-000000000001","claimId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","procedureDesc":"example-proceduredesc","units":1,"expectedAmount":125.5,"idempotencyKey":"example-idempotencykey"}}},"description":"`patientId`, `procedureCode`, and `serviceDate` are required. `units` defaults to 1 and must be a positive integer. `expectedAmount` can be a number or decimal string. `procedureDesc`, `encounterId`, `claimId`, and `facilityId` are optional."},"responses":{"201":{"description":"Charge capture audit created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/or-reconciliations":{"post":{"operationId":"reconcileRevenueIntegrityOperatingRoomCharges","summary":"Reconcile operating room charges","description":"Creates a local operating room charge reconciliation session from operating room log entries after validating facility and patient ownership.\n\n### When to use\nUse this endpoint when an operating room schedule or case log feed needs Revenue Integrity review for performed surgical or procedure charges.\n\n### Before calling\nAuthenticate with write scope. Resolve `facilityId` and each operating room log `patientId` in the API-key organization. Normalize procedure code and description fields before sending.\n\n### Request guidance\n`facilityId`, `dateRangeStart`, `dateRangeEnd`, and 1 to 1000 `orLogEntries` are required. Each operating room log entry requires `patientId` and `procedureDate`; the API accepts either `procedureCode` or `primaryCptCode`, and either `procedureDesc` or `procedureDescription`.\n\n### Request notes\n- `orLogEntries` is capped at 1000 entries.\n- `caseNumber` becomes the local source record id when supplied.\n- Although extra JSON properties are tolerated by the schema, public examples should use only documented fields.\n\n### Response semantics\nHTTP 201 returns a local reconciliation session id, status `IN_PROGRESS`, mode `created`, and `meta.organizationId`. The local session is labeled for operating room reconciliation and creates local pending reconciliation items. No corrected charge, claim, payer, or Electronic Health Record submission occurs.\n\n### Response notes\n- The response mirrors charge reconciliation creation: local session id, IN_PROGRESS status, and created mode.\n- No corrected charge, claim, payer, or Electronic Health Record submission occurs.\n\n### Errors and retries\n400 can indicate a log entry lacks both accepted procedure-code or procedure-description fields. 404 can indicate wrong-tenant facility or patient identifiers. Check local sessions before retrying after a timeout.\n\n### Error notes\n- 400 can identify the index of an operating room log entry missing required procedure values.\n- 404 can hide wrong-organization patient or facility references.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"facilityId":{"type":"string","minLength":1,"description":"Required QuickRCM facility identifier scoped to the API-key organization."},"dateRangeStart":{"type":"string","format":"date-time","description":"Required ISO datetime lower bound for the operating room reconciliation window."},"dateRangeEnd":{"type":"string","format":"date-time","description":"Required ISO datetime upper bound for the operating room reconciliation window."},"orLogEntries":{"type":"array","items":{"type":"object","properties":{"caseNumber":{"type":"string","minLength":1,"description":"Optional operating room case reference used as the local source record id. Do not include raw scheduling payloads."},"patientId":{"type":"string","minLength":1,"description":"Required QuickRCM patient identifier for each operating room log entry."},"encounterId":{"type":"string","minLength":1,"description":"Optional encounter identifier for the case."},"procedureDate":{"type":"string","format":"date-time","description":"Required ISO datetime for when the procedure occurred."},"procedureCode":{"type":"string","minLength":1,"description":"Optional primary procedure code when `primaryCptCode` is not used."},"primaryCptCode":{"type":"string","minLength":1,"description":"Alternative Current Procedural Terminology code accepted when `procedureCode` is omitted."},"procedureDesc":{"type":"string","minLength":1,"description":"Optional procedure description when `procedureDescription` is not used."},"procedureDescription":{"type":"string","minLength":1,"description":"Alternative procedure description accepted when `procedureDesc` is omitted."},"surgeonName":{"type":"string","minLength":1,"description":"Optional surgeon display name from the operating room log. Use minimum-necessary text."},"roomNumber":{"type":"string","minLength":1,"description":"Optional operating room number or location label."},"orRoomNumber":{"type":"string","minLength":1,"description":"Alternative room-number field accepted when `roomNumber` is omitted."}},"required":["patientId","procedureDate"]},"minItems":1,"maxItems":1000,"description":"Array of operating room case/procedure entries used to seed local reconciliation items. Minimum 1, maximum 1000."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters."}},"required":["facilityId","dateRangeStart","dateRangeEnd","orLogEntries"]},"example":{"facilityId":"00000000-0000-4000-8000-000000000001","dateRangeStart":"2026-06-08T10:15:30Z","dateRangeEnd":"2026-06-08T10:15:30Z","orLogEntries":[{"patientId":"00000000-0000-4000-8000-000000000001","procedureDate":"2026-06-08T10:15:30Z","caseNumber":"example-casenumber","encounterId":"00000000-0000-4000-8000-000000000001","procedureCode":"example-procedurecode","primaryCptCode":"example-primarycptcode","procedureDesc":"example-proceduredesc","procedureDescription":"Example reconcile_revenue_integrity_operating_room_charge note","surgeonName":"Example reconcile_revenue_integrity_operating_room_charge","roomNumber":"example-roomnumber"}],"idempotencyKey":"example-idempotencykey"}}},"description":"`facilityId`, `dateRangeStart`, `dateRangeEnd`, and 1 to 1000 `orLogEntries` are required. Each operating room log entry requires `patientId` and `procedureDate`; the API accepts either `procedureCode` or `primaryCptCode`, and either `procedureDesc` or `procedureDescription`."},"responses":{"201":{"description":"Operating room reconciliation session created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/coding-validations":{"post":{"operationId":"validateRevenueIntegrityCoding","summary":"Validate coding data","description":"Creates a local coding validation result from structured diagnosis and procedure code inputs, with optional claim, billing encounter, patient, Diagnosis-Related Group, encounter-type, Present on Admission, and length-of-stay request context.\n\n### When to use\nUse this endpoint after a coding system or integration has assembled structured codes that need Revenue Integrity review for modifiers, medical necessity, Present on Admission indicators, or Diagnosis-Related Group concerns.\n\n### Before calling\nAuthenticate with write scope. Resolve optional `claimId`, `billingEncounterId`, or `patientId` from the same tenant when those references are known.\n\n### Request guidance\n`dateOfService`, at least one diagnosis code, and at least one procedure code are required. Diagnosis and procedure arrays are each capped at 250. Procedure `codeType` defaults to Current Procedural Terminology (CPT); diagnosis `isPrincipal` defaults to false. `encounterType` is INPATIENT, OUTPATIENT, EMERGENCY, or OBSERVATION when supplied.\n\n### Request notes\n- `dateOfService` must be an ISO datetime.\n- `poaIndicators` require diagnosisCode, poaIndicator, and sequenceNumber for each supplied item.\n- Do not send raw chart transcripts, complete clinical notes, or payer payloads in code descriptions.\n\n### Response semantics\nHTTP 201 returns a local validation result id, status `NEEDS_REVIEW`, mode `created`, and `meta.organizationId`. The immediate response is mutation metadata and does not include detailed validation findings, a final coding decision, or a claim coding update.\n\n### Response notes\n- `status` is `NEEDS_REVIEW` on success.\n- The response does not include detailed validation findings.\n- This endpoint does not update claim coding directly.\n\n### Errors and retries\nA 404 can indicate a referenced claim, billing encounter, or patient is unavailable in the tenant context. Correct schema validation errors before retrying. Check existing validation results before retrying after a timeout because the public contract does not guarantee duplicate suppression.\n\n### Error notes\n- 400 can indicate missing diagnosisCodes or procedureCodes, invalid codeType, or invalid encounterType.\n- 404 can indicate wrong-tenant optional references.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimId":{"type":"string","minLength":1,"description":"Optional QuickRCM claim identifier scoped to the API-key organization."},"billingEncounterId":{"type":"string","minLength":1,"description":"Optional QuickRCM billing encounter identifier scoped to the same organization."},"patientId":{"type":"string","minLength":1,"description":"Optional QuickRCM patient identifier scoped to the same organization."},"dateOfService":{"type":"string","format":"date-time","description":"Required ISO datetime for the service date represented by the coded data."},"encounterType":{"type":"string","enum":["INPATIENT","OUTPATIENT","EMERGENCY","OBSERVATION"],"description":"Optional encounter classification: INPATIENT, OUTPATIENT, EMERGENCY, or OBSERVATION."},"assignedDrg":{"type":"string","minLength":1,"description":"Optional Diagnosis-Related Group code supplied as request context. Do not treat the create response as DRG validation output."},"diagnosisCodes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"Procedure, revenue, Diagnosis-Related Group (DRG), or other local code on a contract rate schedule row."},"description":{"type":"string","description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"sequenceNumber":{"type":"integer","minimum":1},"isPrincipal":{"type":"boolean","default":false},"poaIndicator":{"type":"string","minLength":1}},"required":["code"]},"minItems":1,"maxItems":250,"description":"Required array of diagnosis code objects, capped at 250."},"procedureCodes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"Procedure, revenue, Diagnosis-Related Group (DRG), or other local code on a contract rate schedule row."},"description":{"type":"string","description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"codeType":{"type":"string","enum":["CPT","HCPCS","ICD10_PCS"],"default":"CPT","description":"Code set or classification used for a denial, appeal, collection, or claim workflow reason."},"modifiers":{"type":"array","items":{"type":"string"},"default":[],"description":"Array of procedure modifiers on a claim line."}},"required":["code"]},"minItems":1,"maxItems":250,"description":"Required array of procedure code objects, capped at 250."},"poaIndicators":{"type":"array","items":{"type":"object","properties":{"diagnosisCode":{"type":"string","minLength":1,"description":"Diagnosis code supporting the requested service, capped at 40 characters in create and update requests."},"poaIndicator":{"type":"string","minLength":1},"sequenceNumber":{"type":"integer","minimum":1}},"required":["diagnosisCode","poaIndicator","sequenceNumber"]},"description":"Optional Present on Admission indicator entries keyed by diagnosis code and sequence number."},"los":{"type":["integer","null"],"minimum":0,"description":"Optional length of stay as a non-negative integer supplied as request context."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters."}},"required":["dateOfService","diagnosisCodes","procedureCodes"]},"example":{"dateOfService":"2026-06-08T10:15:30Z","diagnosisCodes":[{"code":"ERROR","description":"Example revenue_integrity_coding note","sequenceNumber":1,"isPrincipal":false,"poaIndicator":"example-poaindicator"}],"procedureCodes":[{"code":"ERROR","description":"Example revenue_integrity_coding note","codeType":"CPT","modifiers":[]}],"claimId":"00000000-0000-4000-8000-000000000001","billingEncounterId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","encounterType":"INPATIENT","assignedDrg":"example-assigneddrg","poaIndicators":[{"diagnosisCode":"example-diagnosiscode","poaIndicator":"example-poaindicator","sequenceNumber":1}],"los":1,"idempotencyKey":"example-idempotencykey"}}},"description":"`dateOfService`, at least one diagnosis code, and at least one procedure code are required. Diagnosis and procedure arrays are each capped at 250. Procedure `codeType` defaults to Current Procedural Terminology (CPT); diagnosis `isPrincipal` defaults to false. `encounterType` is INPATIENT, OUTPATIENT, EMERGENCY, or OBSERVATION when supplied."},"responses":{"201":{"description":"Coding validation result created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/contract-rate-validations":{"post":{"operationId":"validateRevenueIntegrityContractRates","summary":"Queue a contract rate validation","description":"Validates organization ownership for a claim and optional payer configuration, then records a local contract-rate validation workflow request.\n\n### When to use\nUse this endpoint when a claim should be checked against configured payer contract terms without performing a direct payer call.\n\n### Before calling\nAuthenticate with write scope. Resolve `claimId` from QuickRCM and optional `payerConfigId` from the same organization.\n\n### Request guidance\n`claimId` is required. `validateOnly`, `dryRun`, and `queueOnly` default to false, false, and true. Mode precedence is `validateOnly` first, `dryRun` second, otherwise `queued`; `queueOnly: false` does not request direct payer or clearinghouse execution.\n\n### Request notes\n- `validateOnly` wins over `dryRun` when both are true.\n- `queueOnly` is not used to enable live external execution.\n- `idempotencyKey` is capped at 200 characters and should not contain Protected Health Information.\n\n### Response semantics\nHTTP 202 returns `id` as the claim id, status QUEUED, VALIDATED, or DRYRUN, the selected mode, and `meta.organizationId`. The response acknowledges a local workflow request and does not perform or return a live rate calculation.\n\n### Response notes\n- 202 means the local workflow request was accepted.\n- The response is not a payer rate confirmation, appeal packet, or underpayment determination.\n\n### Errors and retries\nA 404 can indicate the claim or payer configuration is missing or outside the tenant. The API accepts `idempotencyKey` but does not guarantee duplicate suppression; inspect local workflow state before retrying after timeouts.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant claim or payer configuration references.\n- Do not retry malformed mode controls unchanged.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimId":{"type":"string","minLength":1,"description":"Required QuickRCM claim identifier scoped to the API-key organization."},"payerConfigId":{"type":"string","minLength":1,"description":"Optional organization-scoped payer configuration identifier used to narrow the requested validation workflow."},"validateOnly":{"type":"boolean","default":false,"description":"Highest-precedence safe-action flag. When true, response mode is `validated`."},"dryRun":{"type":"boolean","default":false,"description":"Second-precedence safe-action flag. Used only when `validateOnly` is false."},"queueOnly":{"type":"boolean","default":true,"description":"Schema flag defaulting to true. It does not request direct payer or clearinghouse execution."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters; duplicate suppression is not guaranteed by the public contract."}},"required":["claimId"]},"example":{"claimId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","validateOnly":false,"dryRun":false,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`claimId` is required. `validateOnly`, `dryRun`, and `queueOnly` default to false, false, and true. Mode precedence is `validateOnly` first, `dryRun` second, otherwise `queued`; `queueOnly: false` does not request direct payer or clearinghouse execution."},"responses":{"202":{"description":"Contract rate validation queued or simulated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/implant-recoveries":{"post":{"operationId":"trackRevenueIntegrityImplantRecovery","summary":"Track implant recovery","description":"Creates a local underpayment case of type IMPLANT_COST for an organization-owned claim and records local underpayment workflow activity.\n\n### When to use\nUse this endpoint when implant cost or carve-out recovery needs to be tracked as an underpayment case in QuickRCM.\n\n### Before calling\nAuthenticate with write scope. Resolve `claimId` from the same tenant. Prepare implant cost, description, optional invoice id, and optional expected/actual recovery values.\n\n### Request guidance\n`claimId`, `implantCost`, and `implantDescription` are required. `implantDescription` is capped at 1000 characters and `implantInvoiceId` at 200 characters. When omitted, `expectedRecovery` uses the implant cost and `actualRecovery` starts at zero.\n\n### Request notes\n- `implantCost`, `expectedRecovery`, and `actualRecovery` can be numbers or decimal strings.\n- `implantInvoiceId` should be a sanitized reference, not a storage key, signed URL, or credential.\n- `idempotencyKey` can help caller-side retries but should not be described as guaranteed duplicate prevention.\n\n### Response semantics\nHTTP 201 returns the new underpayment case id, status `IDENTIFIED`, mode `created`, and `meta.organizationId`. The API derives local variance from expected recovery minus actual recovery and does not contact a payer or upload invoices.\n\n### Response notes\n- Status starts as IDENTIFIED.\n- The activity description is local QuickRCM workflow context.\n- No external payer appeal or recovery submission occurs.\n\n### Errors and retries\n404 indicates the claim was missing or outside the tenant. Money inputs must parse as finite numbers or decimal strings. After a timeout, search underpayment cases by claim and case context before retrying.\n\n### Error notes\n- 400 can indicate invalid money amount or missing required implant fields.\n- 404 can indicate wrong-tenant claim context.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimId":{"type":"string","minLength":1,"description":"Required QuickRCM claim identifier scoped to the API-key organization."},"implantCost":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Required implant cost as a number or decimal string."},"expectedRecovery":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional expected recovery amount; defaults to `implantCost` when omitted."},"actualRecovery":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional actual recovered amount used to calculate initial variance; defaults to zero when omitted."},"implantDescription":{"type":"string","minLength":1,"maxLength":1000,"description":"Required implant description capped at 1000 characters. Use minimum-necessary text."},"implantInvoiceId":{"type":"string","minLength":1,"maxLength":200,"description":"Optional sanitized implant invoice reference capped at 200 characters. Do not include S3 keys, signed URLs, or credentials."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters."}},"required":["claimId","implantCost","implantDescription"]},"example":{"claimId":"00000000-0000-4000-8000-000000000001","implantCost":1.25,"implantDescription":"Example track_revenue_integrity_implant_recovery note","expectedRecovery":1.25,"actualRecovery":1.25,"implantInvoiceId":"00000000-0000-4000-8000-000000000001","idempotencyKey":"example-idempotencykey"}}},"description":"`claimId`, `implantCost`, and `implantDescription` are required. `implantDescription` is capped at 1000 characters and `implantInvoiceId` at 200 characters. When omitted, `expectedRecovery` uses the implant cost and `actualRecovery` starts at zero."},"responses":{"201":{"description":"Implant recovery underpayment case created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/underpayment-cases/{caseId}/appeal":{"post":{"operationId":"generateRevenueIntegrityUnderpaymentAppeal","summary":"Queue underpayment appeal generation","description":"Verifies an underpayment case belongs to the authenticated organization and records a local appeal-generation workflow request in validated, dry-run, or queued mode.\n\n### When to use\nUse this endpoint when a confirmed or review-ready underpayment case needs an appeal-generation workflow tracked by QuickRCM.\n\n### Before calling\nAuthenticate with write scope. Use a `caseId` from `listRevenueIntegrityUnderpaymentCases` or another trusted QuickRCM response for the same tenant.\n\n### Request guidance\n`appealLevel` is optional and capped at 100 characters. `validateOnly`, `dryRun`, and `queueOnly` follow the shared Revenue Integrity queued workflow mode rules.\n\n### Request notes\n- `validateOnly` wins over `dryRun` when both are true.\n- `queueOnly: false` does not submit an appeal externally.\n- Use sanitized appeal levels such as FIRST_LEVEL or RECONSIDERATION if those match local policy.\n\n### Response semantics\nHTTP 202 returns `id` as the underpayment case id, status QUEUED, VALIDATED, or DRYRUN, the selected mode, and `meta.organizationId`. The immediate response does not include a generated appeal document and does not submit anything externally.\n\n### Response notes\n- 202 means the local workflow request was accepted.\n- No payer portal, clearinghouse, mail, fax, or Electronic Health Record submission occurs.\n\n### Errors and retries\n404 means the underpayment case is missing or outside the tenant. Re-read case or workflow state after timeouts because the public contract does not guarantee duplicate suppression.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant cases.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"caseId","in":"path","description":"Underpayment case identifier from the path. It must belong to the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"appealLevel":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local appeal level label capped at 100 characters."},"validateOnly":{"type":"boolean","default":false,"description":"Highest-precedence safe-action flag."},"dryRun":{"type":"boolean","default":false,"description":"Second-precedence safe-action flag."},"queueOnly":{"type":"boolean","default":true,"description":"Schema flag defaulting to true. It does not request external appeal submission."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters."}}},"example":{"appealLevel":"example-appeallevel","validateOnly":false,"dryRun":false,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`appealLevel` is optional and capped at 100 characters. `validateOnly`, `dryRun`, and `queueOnly` follow the shared Revenue Integrity queued workflow mode rules."},"responses":{"202":{"description":"Appeal generation queued or simulated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/underpayment-cases/{caseId}/appeal/submit":{"post":{"operationId":"submitRevenueIntegrityUnderpaymentAppeal","summary":"Record underpayment appeal submission","description":"Records local appeal submission metadata for an organization-owned underpayment case.\n\n### When to use\nUse this endpoint after an appeal has been submitted through an approved external channel and QuickRCM needs local tracking metadata.\n\n### Before calling\nAuthenticate with write scope. Confirm the `caseId` belongs to the authenticated organization and prepare sanitized appeal reference metadata.\n\n### Request guidance\n`appealReference` is optional and capped at 200 characters. `appealLevel` is optional and capped at 100 characters. `submittedAt` must be an ISO datetime when supplied; otherwise QuickRCM records the submission using server time.\n\n### Request notes\n- `submittedAt` must be an ISO datetime if present.\n- `appealReference` should be a sanitized reference, not payer portal credentials or raw payer payload.\n- This endpoint records local submission state only.\n\n### Response semantics\nHTTP 200 returns `success: true`, `data.id` as the underpayment case id, `data.status` as the resulting local status, `data.mode: \"updated\"`, and `meta.organizationId`. The handler persists appealReference, appealLevel, submittedAt-derived appealSubmittedAt, and a locally calculated appealDeadline on the case, but those fields are not returned in the immediate submit response. This is local tracking only and does not submit to a payer portal or clearinghouse.\n\n### Response notes\n- The immediate response is an id/status/mode mutation response, not a full underpayment case representation.\n- Appeal reference, appeal level, submitted timestamp, and calculated appeal deadline are persisted as local case metadata and can be observed by re-reading the case list when returned there.\n- No external submission receipt is returned.\n\n### Errors and retries\n404 indicates the case is missing or outside the tenant. If a retry is needed after a timeout, re-read the case first to avoid overwriting newer appeal metadata.\n\n### Error notes\n- 400 can indicate invalid datetime or string length.\n- 404 can intentionally hide wrong-tenant cases.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"caseId","in":"path","description":"Underpayment case identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"appealReference":{"type":"string","minLength":1,"maxLength":200,"description":"Optional sanitized local or external appeal reference capped at 200 characters. It is persisted on the case but is not returned by the immediate submit response."},"appealLevel":{"type":"string","minLength":1,"maxLength":100,"description":"Optional local appeal level label capped at 100 characters. It is persisted on the case but is not returned by the immediate submit response."},"submittedAt":{"type":"string","format":"date-time","description":"Optional ISO datetime for when the external appeal submission occurred."}}},"example":{"appealReference":"example-appealreference","appealLevel":"example-appeallevel","submittedAt":"2026-06-08T10:15:30Z"}}},"description":"`appealReference` is optional and capped at 200 characters. `appealLevel` is optional and capped at 100 characters. `submittedAt` must be an ISO datetime when supplied; otherwise QuickRCM records the submission using server time."},"responses":{"200":{"description":"Appeal submission recorded locally.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"submitted","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/underpayment-cases/{caseId}/recovery":{"post":{"operationId":"recordRevenueIntegrityUnderpaymentRecovery","summary":"Record underpayment recovery","description":"Adds a recovered amount to a tenant-owned underpayment case and records local recovery metadata.\n\n### When to use\nUse this endpoint after a recovery has been confirmed outside the API and QuickRCM needs the underpayment case updated for reporting.\n\n### Before calling\nAuthenticate with write scope. Confirm the `caseId` belongs to the authenticated organization. Prepare a decimal recovered amount and sanitized payment reference if available.\n\n### Request guidance\n`recoveredAmount` is required and can be a number or decimal string. `notes` is optional and capped at 2000 characters. `paymentReference` is optional and capped at 200 characters.\n\n### Request notes\n- `recoveredAmount` is additive.\n- `paymentReference` should be a sanitized reference, not raw Electronic Remittance Advice, check images, tokens, or bank data.\n- Use notes for concise local context only.\n\n### Response semantics\nHTTP 200 increments the local recovered amount and returns `success: true`, `data.id` as the underpayment case id, `data.status` as the resulting local status, `data.recoveredAmount` as the cumulative recovered amount decimal string, `data.mode: \"updated\"`, and `meta.organizationId`. This does not post cash, update Electronic Remittance Advice records, or change payment records.\n\n### Response notes\n- Status may become RECOVERED when cumulative recovery reaches the case recovery threshold.\n- The immediate response returns cumulative recovered amount as a decimal string plus id/status/mode.\n- `varianceAmount` is existing case state used internally to decide the resulting status; it is not accepted in this request and is not returned by this immediate response.\n- No payment posting side effect is implied.\n\n### Errors and retries\n404 indicates the case is missing or outside the tenant. Re-read the case before retrying after a timeout because recovery recording is additive.\n\n### Error notes\n- 400 can indicate an invalid or missing recoveredAmount.\n- 404 can intentionally hide wrong-tenant cases.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"caseId","in":"path","description":"Underpayment case identifier from the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recoveredAmount":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Required amount to add to the underpayment case recovery total. Use a number or decimal string."},"notes":{"type":"string","maxLength":2000,"description":"Optional recovery note capped at 2000 characters. Avoid PHI, raw payer payloads, and bank data."},"paymentReference":{"type":"string","minLength":1,"maxLength":200,"description":"Optional sanitized recovery/payment reference capped at 200 characters."}},"required":["recoveredAmount"]},"example":{"recoveredAmount":125.5,"notes":"Example revenue_integrity_underpayment_recovery note","paymentReference":"example-paymentreference"}}},"description":"`recoveredAmount` is required and can be a number or decimal string. `notes` is optional and capped at 2000 characters. `paymentReference` is optional and capped at 200 characters."},"responses":{"200":{"description":"Underpayment recovery recorded locally.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/rate-validations/bulk":{"post":{"operationId":"bulkValidateRevenueIntegrityRates","summary":"Queue bulk rate validation","description":"Validates optional payer/facility ownership and records a local bulk rate validation workflow request over a date range.\n\n### When to use\nUse this endpoint when an integration wants QuickRCM to schedule or track a broad contract-rate validation workflow without making direct payer calls.\n\n### Before calling\nAuthenticate with write scope. Choose a bounded date range. Resolve optional `payerConfigId` and `facilityId` from the same organization.\n\n### Request guidance\n`dateRangeStart` and `dateRangeEnd` are required ISO datetimes. Optional `validateOnly`, `dryRun`, and `queueOnly` follow the same mode precedence as other Revenue Integrity queued workflows: validateOnly, then dryRun, otherwise queued.\n\n### Request notes\n- `dateRangeStart` and `dateRangeEnd` must be ISO datetimes.\n- `payerConfigId` and `facilityId` are filters, not tenant selectors.\n- `queueOnly: false` does not make this a direct payer call.\n\n### Response semantics\nHTTP 202 returns `id: null`, status QUEUED, VALIDATED, or DRYRUN, selected mode, and `meta.organizationId`. The response does not include bulk validation results or per-claim findings.\n\n### Response notes\n- `id` is null in the success response.\n- No per-claim result set is returned by this endpoint.\n\n### Errors and retries\n404 can indicate supplied payer or facility references are outside the tenant. Use backoff on 429. Inspect local workflow state before retrying after a timeout.\n\n### Error notes\n- 400 can indicate malformed date-time or mode fields.\n- 404 can indicate wrong-tenant payer or facility references.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dateRangeStart":{"type":"string","format":"date-time","description":"Required ISO datetime lower bound for the bulk validation window."},"dateRangeEnd":{"type":"string","format":"date-time","description":"Required ISO datetime upper bound for the bulk validation window."},"payerConfigId":{"type":"string","minLength":1,"description":"Optional organization-scoped payer configuration filter."},"facilityId":{"type":"string","minLength":1,"description":"Optional organization-scoped facility filter."},"validateOnly":{"type":"boolean","default":false,"description":"Highest-precedence safe-action flag."},"dryRun":{"type":"boolean","default":false,"description":"Second-precedence safe-action flag."},"queueOnly":{"type":"boolean","default":true,"description":"Schema flag defaulting to true. It does not request direct payer execution."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters."}},"required":["dateRangeStart","dateRangeEnd"]},"example":{"dateRangeStart":"2026-06-08T10:15:30Z","dateRangeEnd":"2026-06-08T10:15:30Z","payerConfigId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","validateOnly":false,"dryRun":false,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`dateRangeStart` and `dateRangeEnd` are required ISO datetimes. Optional `validateOnly`, `dryRun`, and `queueOnly` follow the same mode precedence as other Revenue Integrity queued workflows: validateOnly, then dryRun, otherwise queued."},"responses":{"202":{"description":"Bulk rate validation queued or simulated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/contracts":{"post":{"operationId":"createRevenueIntegrityContract","summary":"Create an insurance contract","description":"Creates an organization-owned insurance contract with optional facility scope and optional rate schedule rows after validating payer and facility references.\n\n### When to use\nUse this endpoint to load local payer contract terms that Revenue Integrity workflows can later use for rate validation and underpayment analysis.\n\n### Before calling\nAuthenticate with write scope. Resolve `payerConfigId` and optional `facilityId` in the same tenant. Prepare effective dates, base rate type, optional thresholds, terms, notes, and up to 1000 rate schedules.\n\n### Request guidance\n`payerConfigId`, `contractName`, `effectiveDate`, and `baseRateType` are required. `contractName` is capped at 255 characters and `contractNumber` at 100. `notes` is capped at 5000 characters. `rateSchedules` defaults to an empty array and is capped at 1000. Rate schedule `codeType` is Current Procedural Terminology (CPT), Healthcare Common Procedure Coding System (HCPCS), Diagnosis-Related Group (DRG), or revenue code (REV_CODE).\n\n### Request notes\n- `baseRateType` and rate schedule `rateType` use the Revenue Integrity contract rate type enum.\n- Money fields accept numbers or decimal strings. Prefer decimal strings in examples to preserve cents.\n- `terms` is structured JSON for local contract terms; do not include credentials, raw payer payloads, or signed document URLs.\n\n### Response semantics\nHTTP 201 returns the local contract id, status `ACTIVE`, mode `created`, and `meta.organizationId`. It creates local contract/rate schedule records only; it does not validate historical claims by itself.\n\n### Response notes\n- Status is returned as ACTIVE on success.\n- Contract validation is a separate workflow.\n- The response does not include the created rate schedule rows.\n\n### Errors and retries\n404 can indicate wrong-tenant payer or facility references. Check for an existing contract before retrying after a timeout because the public contract does not guarantee idempotent replay.\n\n### Error notes\n- 400 can indicate invalid enum, date-time, money, or string length values.\n- 404 can indicate supplied payer or facility is not available to the tenant.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payerConfigId":{"type":"string","minLength":1,"description":"Required organization-scoped payer configuration identifier."},"facilityId":{"type":"string","minLength":1,"description":"Optional facility scope for the contract. If omitted, the contract is not tied to one public facility id."},"contractName":{"type":"string","minLength":1,"maxLength":255,"description":"Required human-readable contract name capped at 255 characters."},"contractNumber":{"type":"string","minLength":1,"maxLength":100,"description":"Optional sanitized contract number capped at 100 characters."},"effectiveDate":{"type":"string","format":"date-time","description":"Required ISO datetime when the contract terms start."},"terminationDate":{"type":"string","format":"date-time","description":"Optional ISO datetime when the contract terms end."},"baseRateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"],"description":"Required contract base rate type: FEE_SCHEDULE, PER_DIEM, DRG_BASED, CASE_RATE, PERCENT_OF_CHARGE, MEDICARE_PERCENT, CAPITATED, STOP_LOSS, OUTLIER, or CARVE_OUT."},"baseRate":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional base monetary or percentage value, depending on `baseRateType`. Use a number or decimal string."},"medicarePercent":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional Medicare percentage value used when Medicare-percent contract terms apply."},"stopLossThreshold":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional charge or cost threshold where stop-loss terms begin."},"stopLossPercent":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional percentage applied to stop-loss calculations."},"stopLossMinCharges":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional minimum charges required before stop-loss terms apply."},"outlierThreshold":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional threshold used for outlier payment terms."},"outlierPercent":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional percentage applied to outlier calculations."},"implantCarveOut":{"type":"boolean","default":false,"description":"Boolean flag indicating whether implant carve-out terms are configured locally."},"implantMarkupPercent":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional percentage markup for implant carve-out terms."},"implantMinCost":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional minimum implant cost threshold for implant carve-out terms."},"terms":{"type":"object","additionalProperties":{},"description":"Optional structured JSON for local contract terms. Keep it free of secrets and raw payer documents."},"notes":{"type":"string","maxLength":5000,"description":"Optional local contract notes capped at 5000 characters. Avoid credentials, raw payer payloads, and unnecessary PHI."},"rateSchedules":{"type":"array","items":{"type":"object","properties":{"rateType":{"type":"string","enum":["FEE_SCHEDULE","PER_DIEM","DRG_BASED","CASE_RATE","PERCENT_OF_CHARGE","MEDICARE_PERCENT","CAPITATED","STOP_LOSS","OUTLIER","CARVE_OUT"]},"code":{"type":"string","minLength":1,"description":"Procedure, revenue, Diagnosis-Related Group (DRG), or other local code on a contract rate schedule row."},"codeType":{"type":"string","enum":["CPT","HCPCS","DRG","REV_CODE"],"description":"Code set or classification used for a denial, appeal, collection, or claim workflow reason."},"description":{"type":"string","description":"Human-readable description of the queue, workflow, or record. Avoid secrets and unnecessary PHI."},"rate":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Primary decimal rate amount for a contract rate schedule row, returned as a string."},"ratePercent":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional percentage-style decimal rate for a contract rate schedule row."},"perDiemRate":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional daily decimal rate for a per-diem contract rate schedule row."},"caseRate":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional case-level decimal rate for a contract rate schedule row."},"minRate":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional minimum decimal amount for a bounded contract rate schedule row."},"maxRate":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}],"description":"Optional maximum decimal amount for a bounded contract rate schedule row."},"effectiveDate":{"type":"string","format":"date-time","description":"Required ISO datetime when the contract terms start."},"terminationDate":{"type":"string","format":"date-time","description":"Optional ISO datetime when the contract terms end."}},"required":["rateType","code","codeType","rate"]},"maxItems":1000,"default":[],"description":"Optional array of local rate schedule rows, capped at 1000."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters."}},"required":["payerConfigId","contractName","effectiveDate","baseRateType"]},"example":{"payerConfigId":"00000000-0000-4000-8000-000000000001","contractName":"Example revenue_integrity_contract","effectiveDate":"2026-06-08T10:15:30Z","baseRateType":"FEE_SCHEDULE","facilityId":"00000000-0000-4000-8000-000000000001","contractNumber":"example-contractnumber","terminationDate":"2026-06-08T10:15:30Z","baseRate":1.25,"medicarePercent":1.25,"stopLossThreshold":1.25,"stopLossPercent":1.25,"stopLossMinCharges":125.5}}},"description":"`payerConfigId`, `contractName`, `effectiveDate`, and `baseRateType` are required. `contractName` is capped at 255 characters and `contractNumber` at 100. `notes` is capped at 5000 characters. `rateSchedules` defaults to an empty array and is capped at 1000. Rate schedule `codeType` is Current Procedural Terminology (CPT), Healthcare Common Procedure Coding System (HCPCS), Diagnosis-Related Group (DRG), or revenue code (REV_CODE)."},"responses":{"201":{"description":"Insurance contract created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/revenue-integrity/underpayment-checks/manual":{"post":{"operationId":"triggerRevenueIntegrityManualUnderpaymentCheck","summary":"Queue a manual underpayment check","description":"Verifies claim ownership and records a local manual underpayment-check workflow request in validated, dry-run, or queued mode.\n\n### When to use\nUse this endpoint when an integration or operator wants QuickRCM to track a manual underpayment check request for a specific claim.\n\n### Before calling\nAuthenticate with write scope. Resolve `claimId` from the same organization.\n\n### Request guidance\n`claimId` is required. `validateOnly`, `dryRun`, and `queueOnly` default to false, false, and true. Mode precedence is validateOnly, then dryRun, otherwise queued; `queueOnly: false` does not enable direct payer calls.\n\n### Request notes\n- `idempotencyKey` is accepted but should not contain Protected Health Information and should not be described as guaranteed dedupe enforcement.\n- Use `validateOnly` or `dryRun` for setup testing.\n- This endpoint does not prove an underpayment exists.\n\n### Response semantics\nHTTP 202 returns `id` as the claim id, status QUEUED, VALIDATED, or DRYRUN, selected mode, and `meta.organizationId`. The response does not return underpayment findings, payer responses, or case creation results.\n\n### Response notes\n- 202 means the local workflow request was accepted.\n- No payer response, Electronic Remittance Advice review result, or case creation is returned by this endpoint.\n\n### Errors and retries\n404 can indicate the claim is missing or outside the tenant. After timeouts, inspect local workflow state before retrying because the public contract does not guarantee duplicate suppression.\n\n### Error notes\n- 404 can intentionally hide wrong-tenant claim ids.\n","tags":["Revenue Integrity"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"claimId":{"type":"string","minLength":1,"description":"Required QuickRCM claim identifier. It must belong to the organization selected by the bearer API key."},"validateOnly":{"type":"boolean","default":false,"description":"Highest-precedence safe-action flag."},"dryRun":{"type":"boolean","default":false,"description":"Second-precedence safe-action flag."},"queueOnly":{"type":"boolean","default":true,"description":"Schema flag defaulting to true. It does not request direct payer execution."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller retry marker capped at 200 characters."}},"required":["claimId"]},"example":{"claimId":"00000000-0000-4000-8000-000000000001","validateOnly":false,"dryRun":false,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`claimId` is required. `validateOnly`, `dryRun`, and `queueOnly` default to false, false, and true. Mode precedence is validateOnly, then dryRun, otherwise queued; `queueOnly: false` does not enable direct payer calls."},"responses":{"202":{"description":"Manual underpayment check queued or simulated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":["string","null"]},"status":{"type":"string"},"mode":{"type":"string","enum":["created","updated","queued","validated","dryRun"]}}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","status":"active","mode":"created"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/risk-adjustment/jobs":{"get":{"operationId":"listRiskAdjustmentJobs","summary":"List risk adjustment jobs","description":"Lists paginated risk adjustment jobs for the organization selected by the bearer API key, with optional status and patient filters.\n\n### When to use\nUse this endpoint to monitor queued, processing, completed, failed, cancelled, or partially failed risk adjustment jobs or to populate a tenant-scoped worklist.\n\n### Before calling\nAuthenticate with a public API key that has `risk-adjustment:read` or `risk-adjustment:write`. Choose pagination before polling; `page` is one-based and `pageSize` is capped at 100. Use `patientId` only when it is a QuickRCM patient identifier from the authenticated organization.\n\n### Request guidance\nSend query parameters only. `page` defaults to 1 and accepts 1 through 10000. `pageSize` defaults to 25 and accepts 1 through 100. `status` must be one of the documented risk adjustment job status enum values. Do not send `organizationId`; tenant context comes from the bearer API key.\n\n### Request notes\n- `status` filters by processing lifecycle values such as `PENDING`, `TIER1_PROCESSING`, `COMPLETED`, `FAILED`, `CANCELLED`, and `PARTIAL_FAILURE`.\n- `patientId` is a QuickRCM patient identifier, not a demographics search field.\n- Use smaller pages for active polling to reduce repeated exposure of patient-linked job metadata.\n\n### Response semantics\nHTTP 200 returns `data.jobs`, `total`, `page`, `pageSize`, `totalPages`, and `meta.organizationId`. Each job summary includes local identifiers, lifecycle status, progress/counter fields, RAF score fields, cost fields, review booleans, and lifecycle timestamps. The list response does not include HCC code arrays, patient summaries, raw evidence text, or document chunks.\n\n### Response notes\n- `progress` is bounded from 0 through 100.\n- `rafScore` and `finalizedRafScore` can be null depending on processing and review state.\n- `organizationId` appears in resource rows and metadata as response context, not as a public request selector.\n\n### Errors and retries\nTreat 400 as invalid pagination or filter input, 401/403 as credential or tenant authorization failures, 429 as a backoff signal, and 500 as retryable only with bounded retry logic. 402, 404, and 409 are declared common responses in the generated OpenAPI contract, but this read endpoint should not be described as a normal credit-consuming or duplicate-conflict workflow. Empty result sets should be documented as HTTP 200 with an empty `jobs` array.\n\n### Error notes\n- 400 can indicate out-of-range `page` or `pageSize` or an unsupported status enum.\n- 404 is declared for tenant-scoped resources but should not be used for normal empty result pages.\n- 429 should be retried with scheduled or exponential backoff.\n","tags":["Risk Adjustment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":10000,"default":1},"required":false,"name":"page","in":"query","description":"One-based result page to return. Defaults to 1 and is capped at 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"Number of jobs per page. Defaults to 25 and is capped at 100."},{"schema":{"type":"string","enum":["PENDING","INGESTING","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","AGGREGATING","COMPLETED","FAILED","CANCELLED","PARTIAL_FAILURE"]},"required":false,"name":"status","in":"query","description":"Optional risk adjustment processing status filter."},{"schema":{"type":"string","minLength":1},"required":false,"name":"patientId","in":"query","description":"Optional QuickRCM patient identifier used to filter jobs within the authenticated organization."}],"responses":{"200":{"description":"Risk adjustment jobs for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"fileId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","INGESTING","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","AGGREGATING","COMPLETED","FAILED","CANCELLED","PARTIAL_FAILURE"]},"currentStage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"totalPages":{"type":["integer","null"],"minimum":0},"totalChunks":{"type":"integer","minimum":0},"relevantChunks":{"type":"integer","minimum":0},"tier1AcceptedChunks":{"type":"integer","minimum":0},"tier2EscalatedChunks":{"type":"integer","minimum":0},"discardedChunks":{"type":"integer","minimum":0},"totalConditions":{"type":"integer","minimum":0},"confirmedHccCodes":{"type":"integer","minimum":0},"rafScore":{"type":["number","null"]},"totalCostUsd":{"type":"number","minimum":0},"creditsCost":{"type":"integer","minimum":0},"requiresHumanReview":{"type":"boolean"},"humanReviewCompleted":{"type":"boolean"},"finalizedRafScore":{"type":["number","null"]},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","fileId","appointmentId","status","currentStage","progress","totalPages","totalChunks","relevantChunks","tier1AcceptedChunks","tier2EscalatedChunks","discardedChunks","totalConditions","confirmedHccCodes","rafScore","totalCostUsd","creditsCost","requiresHumanReview","humanReviewCompleted","finalizedRafScore","startedAt","completedAt","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1},"totalPages":{"type":"integer","minimum":0}},"required":["jobs","total","page","pageSize","totalPages"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"jobs":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","fileId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"PENDING","currentStage":"example-currentstage","progress":1,"totalPages":1,"totalChunks":1,"relevantChunks":1,"tier1AcceptedChunks":1,"tier2EscalatedChunks":1,"discardedChunks":1,"totalConditions":1,"confirmedHccCodes":1,"rafScore":1.25,"totalCostUsd":1,"creditsCost":1,"requiresHumanReview":true,"humanReviewCompleted":true,"finalizedRafScore":1.25,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1,"totalPages":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for the requested risk adjustment workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested risk adjustment resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting risk adjustment job already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createRiskAdjustmentJob","summary":"Create risk adjustment job","description":"Validates a patient-document pair and creates a queued risk adjustment job for the authenticated organization when not running validation only.\n\n### When to use\nUse this after an integration has uploaded or selected an organization-owned QuickRCM File that contains clinical-document evidence for an organization-owned QuickRCM Patient.\n\n### Before calling\nAuthenticate with `risk-adjustment:write`. Resolve `patientId` and `fileId` from QuickRCM records in the same tenant. Include `appointmentId` only when the document should be linked to a known QuickRCM appointment. Use `validateOnly: true` first when checking references, permissions, and estimated credits before queueing.\n\n### Request guidance\n`patientId` and `fileId` are required non-empty strings. `appointmentId`, `validateOnly`, `queueOnly`, and `idempotencyKey` are optional. `queueOnly` defaults to true; for non-validation requests, public processing is queue-only and `queueOnly: false` should be treated as invalid. Do not include raw document contents, transcripts, payer payloads, S3 keys, presigned URLs, or EHR payloads in the request body.\n\n### Request notes\n- `patientId` and `fileId` must refer to QuickRCM records in the API key organization.\n- `appointmentId` is optional because the risk adjustment job workflow can exist without the appointment hub link.\n- `idempotencyKey` is exposed by the schema and capped at 200 characters, but public docs should not promise server-side deduplication behavior beyond the contract.\n\n### Response semantics\nHTTP 200 means the request was validated without queueing. HTTP 202 means a local risk adjustment job was created and queued for processing. The queued response returns the local job summary but does not mean completed risk scoring, human review completion, CMS submission, payer acceptance, claim adjudication, or EHR write-back.\n\n### Response notes\n- Use the HTTP status code and `queued` flag together to distinguish validation from queued work.\n- A queued job starts with local workflow state such as `PENDING` and `Queued for processing`.\n- `estimatedCredits` appears in validation output; queued responses may omit it.\n\n### Errors and retries\nFix 400 validation failures before retrying. A 402 means insufficient credits for the estimated workflow. A 404 can mean the patient, file, or appointment was not found in the authenticated organization. A 409 indicates an active same-tenant job already exists for the patient/file pair; the duplicate check excludes only FAILED and CANCELLED jobs. If a network timeout occurs after a non-validation request, check for an existing job before creating another one, even when an `idempotencyKey` was supplied.\n\n### Error notes\n- 400 can indicate missing required IDs, invalid safety flags, or an overlong `idempotencyKey`.\n- 402 is declared for insufficient credits.\n- 409 should be surfaced as an existing active workflow rather than retried blindly.\n","tags":["Risk Adjustment"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"Required QuickRCM patient identifier in the authenticated organization."},"fileId":{"type":"string","minLength":1,"description":"Required QuickRCM file identifier for the clinical-document evidence to process."},"appointmentId":{"type":"string","minLength":1,"description":"Optional QuickRCM appointment identifier to link the job to encounter context."},"validateOnly":{"type":"boolean","default":false,"description":"When true, validates the request and returns validation output without queueing a job."},"queueOnly":{"type":"boolean","default":true,"description":"Safety flag that defaults to true. Non-validation public requests queue local workflow work instead of directly invoking OCR or AI processing."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller-provided key capped at 200 characters. Do not document stronger deduplication guarantees than the OpenAPI contract provides."}},"required":["patientId","fileId"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","fileId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","validateOnly":false,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`patientId` and `fileId` are required non-empty strings. `appointmentId`, `validateOnly`, `queueOnly`, and `idempotencyKey` are optional. `queueOnly` defaults to true; for non-validation requests, public processing is queue-only and `queueOnly: false` should be treated as invalid. Do not include raw document contents, transcripts, payer payloads, S3 keys, presigned URLs, or EHR payloads in the request body."},"responses":{"200":{"description":"Risk adjustment job request validated without queueing.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean"},"queueOnly":{"type":"boolean"},"valid":{"type":"boolean"},"estimatedCredits":{"type":"integer","minimum":0},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"fileId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","INGESTING","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","AGGREGATING","COMPLETED","FAILED","CANCELLED","PARTIAL_FAILURE"]},"currentStage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"totalPages":{"type":["integer","null"],"minimum":0},"totalChunks":{"type":"integer","minimum":0},"relevantChunks":{"type":"integer","minimum":0},"tier1AcceptedChunks":{"type":"integer","minimum":0},"tier2EscalatedChunks":{"type":"integer","minimum":0},"discardedChunks":{"type":"integer","minimum":0},"totalConditions":{"type":"integer","minimum":0},"confirmedHccCodes":{"type":"integer","minimum":0},"rafScore":{"type":["number","null"]},"totalCostUsd":{"type":"number","minimum":0},"creditsCost":{"type":"integer","minimum":0},"requiresHumanReview":{"type":"boolean"},"humanReviewCompleted":{"type":"boolean"},"finalizedRafScore":{"type":["number","null"]},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","fileId","appointmentId","status","currentStage","progress","totalPages","totalChunks","relevantChunks","tier1AcceptedChunks","tier2EscalatedChunks","discardedChunks","totalConditions","confirmedHccCodes","rafScore","totalCostUsd","creditsCost","requiresHumanReview","humanReviewCompleted","finalizedRafScore","startedAt","completedAt","createdAt","updatedAt"]}},"required":["queued","queueOnly"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"queueOnly":true,"valid":true,"estimatedCredits":1,"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","fileId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"PENDING","currentStage":"example-currentstage","progress":1,"totalPages":1,"totalChunks":1,"relevantChunks":1,"tier1AcceptedChunks":1,"tier2EscalatedChunks":1,"discardedChunks":1,"totalConditions":1,"confirmedHccCodes":1,"rafScore":1.25,"totalCostUsd":1,"creditsCost":1,"requiresHumanReview":true,"humanReviewCompleted":true,"finalizedRafScore":1.25,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Risk adjustment job created and queued for processing.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean"},"queueOnly":{"type":"boolean"},"valid":{"type":"boolean"},"estimatedCredits":{"type":"integer","minimum":0},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"fileId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","INGESTING","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","AGGREGATING","COMPLETED","FAILED","CANCELLED","PARTIAL_FAILURE"]},"currentStage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"totalPages":{"type":["integer","null"],"minimum":0},"totalChunks":{"type":"integer","minimum":0},"relevantChunks":{"type":"integer","minimum":0},"tier1AcceptedChunks":{"type":"integer","minimum":0},"tier2EscalatedChunks":{"type":"integer","minimum":0},"discardedChunks":{"type":"integer","minimum":0},"totalConditions":{"type":"integer","minimum":0},"confirmedHccCodes":{"type":"integer","minimum":0},"rafScore":{"type":["number","null"]},"totalCostUsd":{"type":"number","minimum":0},"creditsCost":{"type":"integer","minimum":0},"requiresHumanReview":{"type":"boolean"},"humanReviewCompleted":{"type":"boolean"},"finalizedRafScore":{"type":["number","null"]},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","fileId","appointmentId","status","currentStage","progress","totalPages","totalChunks","relevantChunks","tier1AcceptedChunks","tier2EscalatedChunks","discardedChunks","totalConditions","confirmedHccCodes","rafScore","totalCostUsd","creditsCost","requiresHumanReview","humanReviewCompleted","finalizedRafScore","startedAt","completedAt","createdAt","updatedAt"]}},"required":["queued","queueOnly"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"queueOnly":true,"valid":true,"estimatedCredits":1,"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","fileId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"PENDING","currentStage":"example-currentstage","progress":1,"totalPages":1,"totalChunks":1,"relevantChunks":1,"tier1AcceptedChunks":1,"tier2EscalatedChunks":1,"discardedChunks":1,"totalConditions":1,"confirmedHccCodes":1,"rafScore":1.25,"totalCostUsd":1,"creditsCost":1,"requiresHumanReview":true,"humanReviewCompleted":true,"finalizedRafScore":1.25,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for the requested risk adjustment workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested risk adjustment resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting risk adjustment job already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/risk-adjustment/jobs/{jobId}":{"get":{"operationId":"getRiskAdjustmentJob","summary":"Get risk adjustment job","description":"Returns one tenant-scoped risk adjustment job with sanitized HCC result summaries when the job belongs to the authenticated organization.\n\n### When to use\nUse this endpoint to display job progress, review readiness, RAF score fields, HCC code summaries, and limited extracted patient summary fields for a known job.\n\n### Before calling\nAuthenticate with `risk-adjustment:read` or `risk-adjustment:write`. Store or retrieve the QuickRCM `jobId` returned by create, bulk-create, list, or reprocess workflows.\n\n### Request guidance\nPass `jobId` in the path. Do not add an `organizationId` query parameter. Do not rely on this endpoint to retrieve source documents, raw document chunks, raw evidence text, clinical note text, transcripts, raw EHR payloads, or raw patient summaries.\n\n### Request notes\n- `jobId` is required and must identify a job in the API key organization.\n- Poll this endpoint for asynchronous progress instead of assuming create or reprocess completed scoring synchronously.\n- Use `reviewRiskAdjustmentHccCode` for individual HCC review decisions rather than attempting to mutate job detail from this read endpoint.\n\n### Response semantics\nHTTP 200 returns `data.job`, including job summary fields, `hccCodes`, and a limited `patientSummary` object with `extractedAge`, `extractedSex`, and `enrollmentModel` when available. HCC code summaries include ICD-10/HCC metadata, RAF weight, confidence, source, active/review flags, review timestamp, and review decision. Raw evidence text and review notes are not returned.\n\n### Response notes\n- `hccCodes` contains HCC summaries, not raw excerpts or source-document chunks.\n- `patientSummary` is limited to extracted age, extracted sex, and enrollment model when present.\n- `requiresHumanReview`, `humanReviewCompleted`, and `finalizedRafScore` should guide downstream review and handoff behavior.\n\n### Errors and retries\nTreat 404 as either a nonexistent job or a job outside the authenticated tenant. Treat 401/403 as credential or permission failures. For 429 or transient 500 responses, retry with backoff and avoid aggressive polling during long-running processing stages. 402 and 409 are declared common responses, but this read endpoint should not be documented as a normal credit-consuming or duplicate-conflict workflow.\n\n### Error notes\n- 404 should be documented as tenant-scoped not found.\n- 429 indicates the client should reduce polling frequency.\n- Do not treat null RAF fields as an error while the job is still processing or awaiting review.\n","tags":["Risk Adjustment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path","description":"QuickRCM risk adjustment job identifier scoped to the authenticated organization."}],"responses":{"200":{"description":"Risk adjustment job detail for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"fileId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","INGESTING","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","AGGREGATING","COMPLETED","FAILED","CANCELLED","PARTIAL_FAILURE"]},"currentStage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"totalPages":{"type":["integer","null"],"minimum":0},"totalChunks":{"type":"integer","minimum":0},"relevantChunks":{"type":"integer","minimum":0},"tier1AcceptedChunks":{"type":"integer","minimum":0},"tier2EscalatedChunks":{"type":"integer","minimum":0},"discardedChunks":{"type":"integer","minimum":0},"totalConditions":{"type":"integer","minimum":0},"confirmedHccCodes":{"type":"integer","minimum":0},"rafScore":{"type":["number","null"]},"totalCostUsd":{"type":"number","minimum":0},"creditsCost":{"type":"integer","minimum":0},"requiresHumanReview":{"type":"boolean"},"humanReviewCompleted":{"type":"boolean"},"finalizedRafScore":{"type":["number","null"]},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"hccCodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"icd10Code":{"type":"string"},"icd10Description":{"type":"string"},"hccCategory":{"type":["integer","null"]},"hccVersion":{"type":"string"},"hccLabel":{"type":["string","null"]},"rafWeight":{"type":["number","null"]},"demographicModel":{"type":["string","null"]},"confidence":{"type":"number","minimum":0,"maximum":1},"source":{"type":"string"},"isActive":{"type":"boolean"},"conditionInteractions":{"type":"array","items":{"type":"string"}},"needsHumanReview":{"type":"boolean"},"humanReviewed":{"type":"boolean"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewDecision":{"type":["string","null"]}},"required":["id","icd10Code","icd10Description","hccCategory","hccVersion","hccLabel","rafWeight","demographicModel","confidence","source","isActive","conditionInteractions","needsHumanReview","humanReviewed","reviewedAt","reviewDecision"]}},"patientSummary":{"type":["object","null"],"properties":{"extractedAge":{"type":["integer","null"]},"extractedSex":{"type":["string","null"]},"enrollmentModel":{"type":["string","null"]}},"required":["extractedAge","extractedSex","enrollmentModel"]}},"required":["id","organizationId","patientId","fileId","appointmentId","status","currentStage","progress","totalPages","totalChunks","relevantChunks","tier1AcceptedChunks","tier2EscalatedChunks","discardedChunks","totalConditions","confirmedHccCodes","rafScore","totalCostUsd","creditsCost","requiresHumanReview","humanReviewCompleted","finalizedRafScore","startedAt","completedAt","createdAt","updatedAt","hccCodes","patientSummary"]}},"required":["job"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","fileId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"PENDING","currentStage":"example-currentstage","progress":1,"totalPages":1,"totalChunks":1,"relevantChunks":1,"tier1AcceptedChunks":1,"tier2EscalatedChunks":1,"discardedChunks":1,"totalConditions":1,"confirmedHccCodes":1,"rafScore":1.25,"totalCostUsd":1,"creditsCost":1,"requiresHumanReview":true,"humanReviewCompleted":true,"finalizedRafScore":1.25,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","hccCodes":[{"id":"00000000-0000-4000-8000-000000000001","icd10Code":"example-icd10code","icd10Description":"Example risk_adjustment_job note","hccCategory":1,"hccVersion":"example-hccversion","hccLabel":"example-hcclabel","rafWeight":1.25,"demographicModel":"example-demographicmodel","confidence":1.25,"source":"example-source","isActive":true,"conditionInteractions":["example-conditioninteractions"],"needsHumanReview":true,"humanReviewed":true,"reviewedAt":"2026-06-08T10:15:30Z","reviewDecision":"example-reviewdecision"}],"patientSummary":{"extractedAge":1,"extractedSex":"example-extractedsex","enrollmentModel":"example-enrollmentmodel"}}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for the requested risk adjustment workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested risk adjustment resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting risk adjustment job already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/risk-adjustment/jobs/bulk":{"post":{"operationId":"bulkCreateRiskAdjustmentJobs","summary":"Bulk create risk adjustment jobs","description":"Validates patient-document pairs and creates queued risk adjustment jobs in bulk for the authenticated organization when not running validation only.\n\n### When to use\nUse this endpoint when an integration needs to queue multiple risk adjustment document workflows after resolving each patient and file in QuickRCM.\n\n### Before calling\nAuthenticate with `risk-adjustment:write`. Build `items` from QuickRCM patient/file pairs that already belong to the API key organization. Keep the batch between 1 and 500 items. Consider `validateOnly: true` before queueing a large batch.\n\n### Request guidance\n`items` is required and must contain 1 through 500 objects, each with required `patientId` and `fileId`. `validateOnly`, `queueOnly`, and `idempotencyKey` are optional. `queueOnly` defaults to true; for non-validation requests, public processing is queue-only and `queueOnly: false` should be treated as invalid. Do not send raw documents, PHI-heavy descriptions, S3 keys, transcripts, payer payloads, or vendor responses in the batch payload.\n\n### Request notes\n- Each item requires only `patientId` and `fileId`; no appointment field is documented for bulk items.\n- `items` is capped at 500.\n- Use a batch-level `idempotencyKey` only as documented by the schema; do not promise per-item deduplication.\n\n### Response semantics\nHTTP 200 means the bulk request validated without queueing. HTTP 202 means local jobs were created and queue dispatch was attempted. The response can include `queued`, `queueOnly`, `valid`, `estimatedCredits`, `count`, `jobIds`, `failedDispatches`, and `meta.organizationId`. `failedDispatches` is an array of local job IDs whose queue dispatch failed; it is not a numeric count and not an external vendor failure report.\n\n### Response notes\n- `count` is the number of local jobs requested or created in the workflow response.\n- `jobIds` lists local QuickRCM job identifiers when jobs are queued or created.\n- `failedDispatches` lists local job IDs that were created but could not be dispatched to the queue.\n\n### Errors and retries\nFix 400 validation errors such as missing items, invalid safety flags, or out-of-range batch size before retrying. Treat 402 as insufficient credits, 404 as at least one referenced local resource missing or outside the tenant, and 409 as either duplicate patient/file pairs in the request or an existing active job for one or more pairs. Active duplicate detection excludes only FAILED and CANCELLED jobs. After timeouts, reconcile with `listRiskAdjustmentJobs` or stored `jobIds` before resubmitting the same batch.\n\n### Error notes\n- 400 can indicate an empty batch, more than 500 items, invalid item shape, or invalid `queueOnly` use.\n- 402 can occur when credits are insufficient for the requested workflow.\n- Bulk retries should be reconciled first to avoid duplicate queued jobs.\n","tags":["Risk Adjustment"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"QuickRCM patient identifier. The patient must belong to the organization selected by the bearer API key."},"fileId":{"type":"string","minLength":1,"description":"QuickRCM file record identifier associated with an appeal supporting document."}},"required":["patientId","fileId"]},"minItems":1,"maxItems":500,"description":"Required array of patient/file pairs to validate or queue for risk adjustment processing."},"validateOnly":{"type":"boolean","default":false,"description":"Validates ownership, authorization, and request shape without creating a task or external submission."},"queueOnly":{"type":"boolean","default":true,"description":"Creates or queues a local QuickRCM task instead of attempting direct payer or clearinghouse execution."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."}},"required":["items"]},"example":{"items":[{"patientId":"00000000-0000-4000-8000-000000000001","fileId":"00000000-0000-4000-8000-000000000001"}],"validateOnly":false,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"`items` is required and must contain 1 through 500 objects, each with required `patientId` and `fileId`. `validateOnly`, `queueOnly`, and `idempotencyKey` are optional. `queueOnly` defaults to true; for non-validation requests, public processing is queue-only and `queueOnly: false` should be treated as invalid. Do not send raw documents, PHI-heavy descriptions, S3 keys, transcripts, payer payloads, or vendor responses in the batch payload."},"responses":{"200":{"description":"Bulk risk adjustment job request validated without queueing.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean"},"queueOnly":{"type":"boolean"},"valid":{"type":"boolean"},"count":{"type":"integer","minimum":0},"jobIds":{"type":"array","items":{"type":"string"}},"failedDispatches":{"type":"array","items":{"type":"string"}},"estimatedCredits":{"type":"integer","minimum":0}},"required":["queued","queueOnly","count","jobIds","failedDispatches"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"queueOnly":true,"count":1,"jobIds":["example-jobids"],"failedDispatches":["example-faileddispatches"],"valid":true,"estimatedCredits":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Bulk risk adjustment jobs created and queued for processing.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean"},"queueOnly":{"type":"boolean"},"valid":{"type":"boolean"},"count":{"type":"integer","minimum":0},"jobIds":{"type":"array","items":{"type":"string"}},"failedDispatches":{"type":"array","items":{"type":"string"}},"estimatedCredits":{"type":"integer","minimum":0}},"required":["queued","queueOnly","count","jobIds","failedDispatches"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"queueOnly":true,"count":1,"jobIds":["example-jobids"],"failedDispatches":["example-faileddispatches"],"valid":true,"estimatedCredits":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for the requested risk adjustment workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested risk adjustment resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting risk adjustment job already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/risk-adjustment/jobs/{jobId}/cancel":{"post":{"operationId":"cancelRiskAdjustmentJob","summary":"Cancel risk adjustment job","description":"Cancels an active queued or processing risk adjustment job in the authenticated organization.\n\n### When to use\nUse this when a queued or in-progress risk adjustment job should no longer proceed because the source file, patient linkage, or workflow request was incorrect or no longer needed.\n\n### Before calling\nAuthenticate with `risk-adjustment:write`. Confirm the job is the intended active workflow and belongs to the authenticated organization. Preserve cancellation rationale in the calling system if needed; the public request schema does not define a reason field.\n\n### Request guidance\nPass `jobId` in the path. The optional JSON body supports `validateOnly`, `queueOnly`, and `idempotencyKey`; no cancellation reason field is documented. `validateOnly: true` checks whether the job can be cancelled without applying cancellation. Do not send raw clinical details or document contents in the body.\n\n### Request notes\n- `jobId` is required in the path.\n- The documented body contains only safety/idempotency flags.\n- Do not document a cancellation reason request field unless the OpenAPI schema adds one.\n\n### Response semantics\nHTTP 200 returns either validation-only output or the updated local job summary with status `CANCELLED`. Cancellation is local QuickRCM workflow state; it does not retract a CMS submission, payer communication, EHR write-back, or claim.\n\n### Response notes\n- Use the returned job status, when present, as the source of truth for local workflow state.\n- No HCC evidence, raw document text, or external cancellation receipt is returned.\n- A 200 response is not an external transaction reversal.\n\n### Errors and retries\nTreat 404 as tenant-scoped not found. Invalid lifecycle state currently returns 400, not 409; document it as an invalid request/state for this endpoint. 402 and 409 are declared common responses, but cancellation should not be described as a normal credit-consuming workflow or duplicate-job conflict. Retrying a cancellation after timeout is usually safe only after reading the job state again.\n\n### Error notes\n- 400 can indicate the job is not in a cancellable state such as `PENDING`, `INGESTING`, `CHUNKING`, `TIER1_PROCESSING`, `ROUTING`, `TIER2_PROCESSING`, or `AGGREGATING`.\n- 404 means the job is not visible in the authenticated organization.\n- 401/403 require credential or permission correction before retrying.\n","tags":["Risk Adjustment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path","description":"QuickRCM risk adjustment job identifier to cancel."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","default":false,"description":"Optional flag to validate cancellation eligibility without applying it."},"queueOnly":{"type":"boolean","default":true,"description":"Optional safety flag exposed by the shared workflow request shape."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Optional caller-provided key capped at 200 characters."}}},"example":{"validateOnly":false,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"Pass `jobId` in the path. The optional JSON body supports `validateOnly`, `queueOnly`, and `idempotencyKey`; no cancellation reason field is documented. `validateOnly: true` checks whether the job can be cancelled without applying cancellation. Do not send raw clinical details or document contents in the body."},"responses":{"200":{"description":"Risk adjustment job cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean"},"queueOnly":{"type":"boolean"},"valid":{"type":"boolean"},"estimatedCredits":{"type":"integer","minimum":0},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"fileId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","INGESTING","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","AGGREGATING","COMPLETED","FAILED","CANCELLED","PARTIAL_FAILURE"]},"currentStage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"totalPages":{"type":["integer","null"],"minimum":0},"totalChunks":{"type":"integer","minimum":0},"relevantChunks":{"type":"integer","minimum":0},"tier1AcceptedChunks":{"type":"integer","minimum":0},"tier2EscalatedChunks":{"type":"integer","minimum":0},"discardedChunks":{"type":"integer","minimum":0},"totalConditions":{"type":"integer","minimum":0},"confirmedHccCodes":{"type":"integer","minimum":0},"rafScore":{"type":["number","null"]},"totalCostUsd":{"type":"number","minimum":0},"creditsCost":{"type":"integer","minimum":0},"requiresHumanReview":{"type":"boolean"},"humanReviewCompleted":{"type":"boolean"},"finalizedRafScore":{"type":["number","null"]},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","fileId","appointmentId","status","currentStage","progress","totalPages","totalChunks","relevantChunks","tier1AcceptedChunks","tier2EscalatedChunks","discardedChunks","totalConditions","confirmedHccCodes","rafScore","totalCostUsd","creditsCost","requiresHumanReview","humanReviewCompleted","finalizedRafScore","startedAt","completedAt","createdAt","updatedAt"]}},"required":["queued","queueOnly"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"queueOnly":true,"valid":true,"estimatedCredits":1,"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","fileId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"PENDING","currentStage":"example-currentstage","progress":1,"totalPages":1,"totalChunks":1,"relevantChunks":1,"tier1AcceptedChunks":1,"tier2EscalatedChunks":1,"discardedChunks":1,"totalConditions":1,"confirmedHccCodes":1,"rafScore":1.25,"totalCostUsd":1,"creditsCost":1,"requiresHumanReview":true,"humanReviewCompleted":true,"finalizedRafScore":1.25,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for the requested risk adjustment workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested risk adjustment resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting risk adjustment job already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/risk-adjustment/jobs/{jobId}/reprocess":{"post":{"operationId":"reprocessRiskAdjustmentJob","summary":"Reprocess risk adjustment job","description":"Validates or resets a terminal risk adjustment job and queues it for reprocessing in the authenticated organization.\n\n### When to use\nUse this when a completed, failed, cancelled, or partially failed job should be rerun after correcting source data, improving document quality, or needing a fresh pipeline pass.\n\n### Before calling\nAuthenticate with `risk-adjustment:write`. Read the job first to verify it is the intended terminal workflow and that rerunning it is operationally appropriate. Consider `validateOnly: true` before queueing a costly reprocess.\n\n### Request guidance\nPass `jobId` in the path. The optional request body supports `validateOnly`, `queueOnly`, and `idempotencyKey`. `queueOnly` defaults to true; for non-validation requests, public processing is queue-only. No request fields are documented for changing patient, file, or appointment linkage during reprocess.\n\n### Request notes\n- `jobId` is required in the path.\n- Terminal statuses for reprocess are `COMPLETED`, `FAILED`, `CANCELLED`, and `PARTIAL_FAILURE`.\n- `idempotencyKey` is optional and capped at 200 characters, but docs should not promise stronger deduplication than the contract states.\n\n### Response semantics\nHTTP 200 means the reprocess request validated without queueing. HTTP 202 means the terminal job was reset to `PENDING` and queued for reprocessing. Existing HCC codes are deactivated, patient summaries and chunks are cleared, and processing counters/scores are reset before the job is queued; the public response returns the reset job summary, not fresh HCC outputs.\n\n### Response notes\n- Use 200 versus 202 to distinguish validation-only from queued reprocessing.\n- HCC scores and review fields should be read later from `getRiskAdjustmentJob`.\n- Queued reprocessing is not CMS submission, payer communication, or EHR write-back.\n\n### Errors and retries\nTreat 400 as invalid request shape, invalid `queueOnly` use, or invalid lifecycle state when the job is not terminal. Invalid lifecycle state currently returns 400, not 409. Treat 402 as insufficient credits and 404 as tenant-scoped not found. 409 is a declared common response but should not be documented as the normal lifecycle-state error for this endpoint. After a timeout, read the job before retrying because the reprocess request may already have reset or queued it.\n\n### Error notes\n- 400 can indicate an attempt to reprocess a non-terminal job.\n- 402 can occur when credits are insufficient.\n- Aggressive retries can create confusing workflow state; re-read the job after ambiguous failures.\n","tags":["Risk Adjustment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path","description":"QuickRCM risk adjustment job identifier to reprocess."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","default":false,"description":"When true, validates reprocessing eligibility without queueing the reset workflow."},"queueOnly":{"type":"boolean","default":true,"description":"Safety flag indicating queued workflow behavior for public callers."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Caller-provided compatibility key used to detect repeated workflow requests. Reuse the same key only for safe retries of the same request."}}},"example":{"validateOnly":false,"queueOnly":true,"idempotencyKey":"example-idempotencykey"}}},"description":"Pass `jobId` in the path. The optional request body supports `validateOnly`, `queueOnly`, and `idempotencyKey`. `queueOnly` defaults to true; for non-validation requests, public processing is queue-only. No request fields are documented for changing patient, file, or appointment linkage during reprocess."},"responses":{"200":{"description":"Risk adjustment reprocess request validated without queueing.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean"},"queueOnly":{"type":"boolean"},"valid":{"type":"boolean"},"estimatedCredits":{"type":"integer","minimum":0},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"fileId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","INGESTING","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","AGGREGATING","COMPLETED","FAILED","CANCELLED","PARTIAL_FAILURE"]},"currentStage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"totalPages":{"type":["integer","null"],"minimum":0},"totalChunks":{"type":"integer","minimum":0},"relevantChunks":{"type":"integer","minimum":0},"tier1AcceptedChunks":{"type":"integer","minimum":0},"tier2EscalatedChunks":{"type":"integer","minimum":0},"discardedChunks":{"type":"integer","minimum":0},"totalConditions":{"type":"integer","minimum":0},"confirmedHccCodes":{"type":"integer","minimum":0},"rafScore":{"type":["number","null"]},"totalCostUsd":{"type":"number","minimum":0},"creditsCost":{"type":"integer","minimum":0},"requiresHumanReview":{"type":"boolean"},"humanReviewCompleted":{"type":"boolean"},"finalizedRafScore":{"type":["number","null"]},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","fileId","appointmentId","status","currentStage","progress","totalPages","totalChunks","relevantChunks","tier1AcceptedChunks","tier2EscalatedChunks","discardedChunks","totalConditions","confirmedHccCodes","rafScore","totalCostUsd","creditsCost","requiresHumanReview","humanReviewCompleted","finalizedRafScore","startedAt","completedAt","createdAt","updatedAt"]}},"required":["queued","queueOnly"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"queueOnly":true,"valid":true,"estimatedCredits":1,"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","fileId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"PENDING","currentStage":"example-currentstage","progress":1,"totalPages":1,"totalChunks":1,"relevantChunks":1,"tier1AcceptedChunks":1,"tier2EscalatedChunks":1,"discardedChunks":1,"totalConditions":1,"confirmedHccCodes":1,"rafScore":1.25,"totalCostUsd":1,"creditsCost":1,"requiresHumanReview":true,"humanReviewCompleted":true,"finalizedRafScore":1.25,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"Risk adjustment job reset and queued for reprocessing.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"queued":{"type":"boolean"},"queueOnly":{"type":"boolean"},"valid":{"type":"boolean"},"estimatedCredits":{"type":"integer","minimum":0},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"patientId":{"type":"string"},"fileId":{"type":"string"},"appointmentId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","INGESTING","CHUNKING","TIER1_PROCESSING","ROUTING","TIER2_PROCESSING","AGGREGATING","COMPLETED","FAILED","CANCELLED","PARTIAL_FAILURE"]},"currentStage":{"type":["string","null"]},"progress":{"type":"integer","minimum":0,"maximum":100},"totalPages":{"type":["integer","null"],"minimum":0},"totalChunks":{"type":"integer","minimum":0},"relevantChunks":{"type":"integer","minimum":0},"tier1AcceptedChunks":{"type":"integer","minimum":0},"tier2EscalatedChunks":{"type":"integer","minimum":0},"discardedChunks":{"type":"integer","minimum":0},"totalConditions":{"type":"integer","minimum":0},"confirmedHccCodes":{"type":"integer","minimum":0},"rafScore":{"type":["number","null"]},"totalCostUsd":{"type":"number","minimum":0},"creditsCost":{"type":"integer","minimum":0},"requiresHumanReview":{"type":"boolean"},"humanReviewCompleted":{"type":"boolean"},"finalizedRafScore":{"type":["number","null"]},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","patientId","fileId","appointmentId","status","currentStage","progress","totalPages","totalChunks","relevantChunks","tier1AcceptedChunks","tier2EscalatedChunks","discardedChunks","totalConditions","confirmedHccCodes","rafScore","totalCostUsd","creditsCost","requiresHumanReview","humanReviewCompleted","finalizedRafScore","startedAt","completedAt","createdAt","updatedAt"]}},"required":["queued","queueOnly"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"queued":true,"queueOnly":true,"valid":true,"estimatedCredits":1,"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","fileId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","status":"PENDING","currentStage":"example-currentstage","progress":1,"totalPages":1,"totalChunks":1,"relevantChunks":1,"tier1AcceptedChunks":1,"tier2EscalatedChunks":1,"discardedChunks":1,"totalConditions":1,"confirmedHccCodes":1,"rafScore":1.25,"totalCostUsd":1,"creditsCost":1,"requiresHumanReview":true,"humanReviewCompleted":true,"finalizedRafScore":1.25,"startedAt":"2026-06-08T10:15:30Z","completedAt":"2026-06-08T10:15:30Z","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for the requested risk adjustment workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested risk adjustment resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting risk adjustment job already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/risk-adjustment/jobs/{jobId}/hcc-codes/{codeId}/review":{"put":{"operationId":"reviewRiskAdjustmentHccCode","summary":"Review risk adjustment HCC code","description":"Records a human review decision for one HCC code on a tenant-scoped risk adjustment job without returning raw evidence text or review notes.\n\n### When to use\nUse this endpoint when a reviewer has approved, rejected, or modified an individual HCC result after inspecting the appropriate clinical evidence in QuickRCM or another approved workflow.\n\n### Before calling\nAuthenticate with `risk-adjustment:write`. Read the job detail, choose the HCC code `id` to review, and ensure the reviewer has enough audited clinical evidence outside the public response to support the decision. If the decision is `modified`, prepare a sanitized replacement `modifiedCode`.\n\n### Request guidance\n`decision` is required and must be `approved`, `rejected`, or `modified`. `modifiedCode` is conditionally required when `decision` is `modified`; it is optional for `approved` and `rejected`. `modifiedCode` is trimmed and capped at 32 characters. `notes` is optional, trimmed, and capped at 2000 characters; keep it minimal, clinically necessary, and free of raw excerpts, transcripts, payer payloads, credentials, tokens, S3 keys, and vendor responses.\n\n### Request notes\n- `decision` is always required.\n- `modifiedCode` is required only when `decision` is `modified`; it is optional for `approved` and `rejected`.\n- `notes` can contain sensitive clinical rationale and should be sanitized in public examples.\n\n### Response semantics\nHTTP 200 returns the updated sanitized `hccCode` summary with ICD-10/HCC metadata, RAF weight, confidence, source, active/review flags, `reviewedAt`, and `reviewDecision`, plus `meta.organizationId`. The response does not return raw evidence text or review notes. A `modified` decision updates the returned `icd10Code` to the supplied `modifiedCode`.\n\n### Response notes\n- The updated `hccCode` summary omits raw evidence and review notes.\n- `humanReviewed`, `reviewedAt`, and `reviewDecision` reflect review state for the individual HCC code.\n- A code-level review response does not itself document job-level finalization or downstream submission.\n\n### Errors and retries\nTreat 400 as invalid decision, missing `modifiedCode` for `decision: \"modified\"`, invalid code shape, or invalid notes shape. Treat 404 as job or HCC code not found in the authenticated organization. 402 and 409 are declared common responses, but this handler should not be documented as a normal credit-consuming or workflow-conflict path. After a timeout, retrieve the job or HCC code summary before repeating the review write.\n\n### Error notes\n- 400 can indicate an unsupported decision enum, missing `modifiedCode` for modified decisions, or overlong notes.\n- 404 can indicate either the job or HCC code is absent from the authenticated tenant.\n- Do not describe this endpoint as recalculating final RAF or finalizing the whole job unless a future contract adds that behavior.\n","tags":["Risk Adjustment"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path","description":"Optional internal or background job identifier associated with a conversion record. It is metadata only in public responses."},{"schema":{"type":"string","minLength":1},"required":true,"name":"codeId","in":"path","description":"QuickRCM risk adjustment HCC code identifier from a job detail response."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approved","rejected","modified"],"description":"Required human review decision. Valid values are `approved`, `rejected`, and `modified`."},"modifiedCode":{"type":"string","minLength":1,"maxLength":32,"description":"Conditionally required replacement code when `decision` is `modified`; capped at 32 characters."},"notes":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional human review note capped at 2000 characters. Keep it sanitized and clinically necessary."}},"required":["decision"]},"example":{"decision":"approved","modifiedCode":"example-modifiedcode","notes":"Example review_risk_adjustment_hcc_code note"}}},"description":"`decision` is required and must be `approved`, `rejected`, or `modified`. `modifiedCode` is conditionally required when `decision` is `modified`; it is optional for `approved` and `rejected`. `modifiedCode` is trimmed and capped at 32 characters. `notes` is optional, trimmed, and capped at 2000 characters; keep it minimal, clinically necessary, and free of raw excerpts, transcripts, payer payloads, credentials, tokens, S3 keys, and vendor responses."},"responses":{"200":{"description":"Risk adjustment HCC code review recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"hccCode":{"type":"object","properties":{"id":{"type":"string"},"icd10Code":{"type":"string"},"icd10Description":{"type":"string"},"hccCategory":{"type":["integer","null"]},"hccVersion":{"type":"string"},"hccLabel":{"type":["string","null"]},"rafWeight":{"type":["number","null"]},"demographicModel":{"type":["string","null"]},"confidence":{"type":"number","minimum":0,"maximum":1},"source":{"type":"string"},"isActive":{"type":"boolean"},"conditionInteractions":{"type":"array","items":{"type":"string"}},"needsHumanReview":{"type":"boolean"},"humanReviewed":{"type":"boolean"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"reviewDecision":{"type":["string","null"]}},"required":["id","icd10Code","icd10Description","hccCategory","hccVersion","hccLabel","rafWeight","demographicModel","confidence","source","isActive","conditionInteractions","needsHumanReview","humanReviewed","reviewedAt","reviewDecision"]}},"required":["hccCode"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"hccCode":{"id":"00000000-0000-4000-8000-000000000001","icd10Code":"example-icd10code","icd10Description":"Example review_risk_adjustment_hcc_code note","hccCategory":1,"hccVersion":"example-hccversion","hccLabel":"example-hcclabel","rafWeight":1.25,"demographicModel":"example-demographicmodel","confidence":1.25,"source":"example-source","isActive":true,"conditionInteractions":["example-conditioninteractions"],"needsHumanReview":true,"humanReviewed":true,"reviewedAt":"2026-06-08T10:15:30Z","reviewDecision":"example-reviewdecision"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"402":{"description":"Insufficient credits for the requested risk adjustment workflow.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request failed","statusCode":402}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Requested risk adjustment resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"Conflicting risk adjustment job already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/scribe/jobs":{"get":{"operationId":"listScribeJobs","summary":"List scribe jobs","description":"Returns paginated scribe job summaries owned by the organization selected by the bearer API key, with optional filters for job status, patient, appointment, and template.\n\n### When to use\nUse this endpoint to build scribe worklists, poll job progress, find jobs before opening detail, or reconcile documentation workflows without retrieving note text.\n\n### Before calling\nAuthenticate with a Scribe read-capable API key. Choose bounded pagination and filters before polling, especially when filtering by patientId or appointmentId.\n\n### Request guidance\n`page` defaults to 1 and is capped at 10000. `pageSize` defaults to 25 and is capped at 100. `status` must be one of `RECORDING`, `UPLOADING`, `TRANSCRIBING`, `GENERATING_NOTE`, `COMPLETED`, `ATTESTED`, or `FAILED`. Do not include a tenant selector; the API key supplies tenant context.\n\n### Request notes\n- Use status and templateId filters to avoid broad clinical-documentation exports.\n- patientId and appointmentId are organization-scoped identifiers and can reveal patient workflow context; avoid logging raw filter values.\n- A Scribe write key is also accepted for read operations, but read-only integrations should use read-capable credentials where available.\n\n### Response semantics\nHTTP 200 returns `data.jobs`, pagination fields, and `meta.organizationId`. Job summaries include template summary metadata, status, audioDurationSeconds, executionMode, and hasFinalNote, but intentionally omit finalNote, raw transcripts, audio URLs, signed URLs, storage references, and vendor payloads.\n\n### Response notes\n- hasFinalNote is a boolean indicator, not the generated note content.\n- template contains only id, name, and specialty in job summary rows.\n- Use getScribeJob only when the integration explicitly needs generated finalNote content.\n\n### Errors and retries\nTreat 400 as invalid pagination or filter input, 401 as missing or invalid bearer credentials, 403 as organization access denial, and 429 as a backoff signal. Retry transient 5xx responses with bounded client retries.\n\n### Error notes\n- 400 can indicate an unsupported status enum or pagination value outside the OpenAPI bounds.\n- 429 should be retried with backoff rather than tight polling.\n- 403 means the authenticated caller cannot access the selected organization context.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":10000,"default":1},"required":false,"name":"page","in":"query","description":"One-based result page. Defaults to 1 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"Maximum number of scribe jobs to return. Defaults to 25 and cannot exceed 100."},{"schema":{"type":"string","enum":["RECORDING","UPLOADING","TRANSCRIBING","GENERATING_NOTE","COMPLETED","ATTESTED","FAILED"]},"required":false,"name":"status","in":"query","description":"Optional local scribe job status filter."},{"schema":{"type":"string","minLength":1},"required":false,"name":"patientId","in":"query","description":"Optional QuickRCM patient identifier filter. Treat as PHI-adjacent workflow context."},{"schema":{"type":"string","minLength":1},"required":false,"name":"appointmentId","in":"query","description":"Optional QuickRCM appointment identifier filter. Appointments are optional in the Scribe workflow."},{"schema":{"type":"string","minLength":1},"required":false,"name":"templateId","in":"query","description":"Optional organization-scoped scribe template identifier filter."}],"responses":{"200":{"description":"Scribe job summaries for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["RECORDING","UPLOADING","TRANSCRIBING","GENERATING_NOTE","COMPLETED","ATTESTED","FAILED"]},"patientId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"templateId":{"type":["string","null"]},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"specialty":{"type":["string","null"]}},"required":["id","name","specialty"]},"audioDurationSeconds":{"type":["integer","null"]},"executionMode":{"type":"string","enum":["AI_ONLY","AI_WITH_HITL"]},"hasFinalNote":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","status","patientId","appointmentId","templateId","template","audioDurationSeconds","executionMode","hasFinalNote","createdAt","updatedAt"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1},"totalPages":{"type":"integer","minimum":0}},"required":["jobs","total","page","pageSize","totalPages"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"jobs":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"RECORDING","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","templateId":"00000000-0000-4000-8000-000000000001","template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example scribe_job","specialty":"example-specialty"},"audioDurationSeconds":1,"executionMode":"AI_ONLY","hasFinalNote":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1,"totalPages":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createScribeJob","summary":"Create scribe job","description":"Creates an organization-scoped scribe job in `UPLOADING` status, validates that the templateId and optional patientId belong to the authenticated organization, stores the supplied audio reference, and immediately attempts to enqueue asynchronous scribe processing.\n\n### When to use\nUse this endpoint when an integration already has an organization-authorized audio reference and wants job creation plus first processing enqueue in one call. Use attachScribeJobFile plus queueScribeJobProcessing when the job already exists or the audio reference is attached separately.\n\n### Before calling\nAuthenticate with a Scribe write-capable API key. Obtain an organization-scoped scribe template from listScribeTemplates or createScribeTemplate, and ensure the fileUrl is authorized for the same tenant. If patientId is supplied, it must identify a patient in the authenticated organization.\n\n### Request guidance\n`fileUrl` and `templateId` are required. `fileUrl` is stored as the job audio reference but is never echoed in public API responses. `fileUrl` is capped at 2048 characters, `language` defaults to `en` and is capped at 20 characters, `annotate` defaults to false, and `executionMode` defaults to `AI_ONLY`. Do not include raw audio bytes, transcripts, tokens, signed URL secrets, storage credentials, or broad clinical context in this JSON body.\n\n### Request notes\n- fileUrl can identify clinical audio access and should not be logged or embedded in public examples as a real URL.\n- templateId is required and must be organization-scoped.\n- Create-job already queues processing; do not tell callers that queueScribeJobProcessing is always required after a successful create response.\n- executionMode must be `AI_ONLY` or `AI_WITH_HITL`.\n\n### Response semantics\nHTTP 201 means the job was created and the asynchronous processing message was accepted. The returned job has local status `UPLOADING`, not a completed transcript or note. The response can include finalNote as string or null, but create responses normally return null; fileUrl, raw transcripts, audio URLs, signed URLs, storage references, and vendor payloads are not returned.\n\n### Response notes\n- The successful response omits the submitted fileUrl.\n- job.status is `UPLOADING` immediately after successful create and enqueue.\n- finalNote is nullable and should be treated as clinical documentation when present.\n- Creation is asynchronous queue acceptance, not inline transcription or note generation.\n\n### Errors and retries\nTreat 400 as invalid request shape, 404 as a missing or wrong-organization template or patient reference, 401/403 as credential or tenant authorization failure, 429 as a backoff signal, and 5xx as a server or queueing failure. Runtime handler evidence shows a 503 created-but-not-queued failure when enqueueing fails after the job record is created, but the generated OpenAPI response list currently documents 500 rather than an explicit 503. Retrying a failed or timed-out POST can create duplicate jobs unless the client performs external de-duplication.\n\n### Error notes\n- 404 can mean the referenced template or patient was not found in the authenticated organization.\n- The queue-failure path is runtime-observed as 503 even though generated OpenAPI currently rolls unexpected server failures into 500.\n- Retried POST calls can create duplicates unless the client coordinates retry behavior externally.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileUrl":{"type":"string","minLength":1,"maxLength":2048,"description":"Organization-authorized audio file URL or reference for transcription. Stored by the workflow but not echoed in public API responses. Maximum length is 2048 characters."},"templateId":{"type":"string","minLength":1,"description":"Required organization-scoped scribe template identifier."},"patientId":{"type":["string","null"],"minLength":1,"description":"Optional organization-scoped patient identifier. Treat as PHI-adjacent workflow context."},"language":{"type":"string","minLength":1,"maxLength":20,"default":"en","description":"Language hint for transcription and note generation. Defaults to `en` and is capped at 20 characters."},"annotate":{"type":"boolean","default":false,"description":"Boolean processing hint. Defaults to false."},"executionMode":{"type":"string","enum":["AI_ONLY","AI_WITH_HITL"],"default":"AI_ONLY","description":"Scribe execution mode. Valid values are `AI_ONLY` and `AI_WITH_HITL`."}},"required":["fileUrl","templateId"]},"example":{"fileUrl":"https://example.quickintell.com/resource","templateId":"00000000-0000-4000-8000-000000000001","patientId":"00000000-0000-4000-8000-000000000001","language":"en","annotate":false,"executionMode":"AI_ONLY"}}},"description":"`fileUrl` and `templateId` are required. `fileUrl` is stored as the job audio reference but is never echoed in public API responses. `fileUrl` is capped at 2048 characters, `language` defaults to `en` and is capped at 20 characters, `annotate` defaults to false, and `executionMode` defaults to `AI_ONLY`. Do not include raw audio bytes, transcripts, tokens, signed URL secrets, storage credentials, or broad clinical context in this JSON body."},"responses":{"201":{"description":"Created scribe job.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["RECORDING","UPLOADING","TRANSCRIBING","GENERATING_NOTE","COMPLETED","ATTESTED","FAILED"]},"patientId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"templateId":{"type":["string","null"]},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"specialty":{"type":["string","null"]}},"required":["id","name","specialty"]},"audioDurationSeconds":{"type":["integer","null"]},"executionMode":{"type":"string","enum":["AI_ONLY","AI_WITH_HITL"]},"hasFinalNote":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"finalNote":{"type":["string","null"]}},"required":["id","organizationId","status","patientId","appointmentId","templateId","template","audioDurationSeconds","executionMode","hasFinalNote","createdAt","updatedAt","finalNote"]}},"required":["job"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"RECORDING","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","templateId":"00000000-0000-4000-8000-000000000001","template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example scribe_job","specialty":"example-specialty"},"audioDurationSeconds":1,"executionMode":"AI_ONLY","hasFinalNote":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","finalNote":"Example scribe_job note"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Template or patient not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/scribe/jobs/{jobId}":{"get":{"operationId":"getScribeJob","summary":"Get scribe job","description":"Returns one organization-scoped scribe job and its generated finalNote field when available.\n\n### When to use\nUse this endpoint after finding a job through listScribeJobs, after a create response, or after queueing processing when an integration needs the job detail and final note text.\n\n### Before calling\nAuthenticate with a Scribe read-capable API key and pass a jobId returned for the same organization. Only call when the integration has a legitimate need to retrieve clinical note text.\n\n### Request guidance\njobId is the only path parameter. Do not send organizationId in the request. Avoid logging jobId when logs could be correlated with patient documentation workflows.\n\n### Request notes\n- jobId must refer to a job in the authenticated organization.\n- Use listScribeJobs first if the integration does not already have jobId.\n- Do not document organizationId as a path, query, or body selector.\n\n### Response semantics\nHTTP 200 returns the scribe job object directly in data, plus meta.organizationId. finalNote can contain generated clinical documentation, while raw transcripts, audio URLs, signed URLs, storage references, and vendor payloads are not returned.\n\n### Response notes\n- finalNote is clinical documentation and can be PHI.\n- The response does not include raw transcript text or audio file access details.\n- template is limited to id, name, and specialty.\n\n### Errors and retries\nTreat 404 as a missing or wrong-organization job, 401/403 as credential or tenant authorization failure, and 429 as a backoff signal. Poll with backoff if waiting for finalNote or status transitions.\n\n### Error notes\n- 404 can mean either no matching job exists or the job is not visible in the authenticated organization.\n- 429 should slow polling frequency.\n- Do not expose raw downstream transcription or LLM failure details in client-facing errors.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path","description":"Required scribe job identifier in the authenticated organization."}],"responses":{"200":{"description":"One organization-scoped scribe job.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["RECORDING","UPLOADING","TRANSCRIBING","GENERATING_NOTE","COMPLETED","ATTESTED","FAILED"]},"patientId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"templateId":{"type":["string","null"]},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"specialty":{"type":["string","null"]}},"required":["id","name","specialty"]},"audioDurationSeconds":{"type":["integer","null"]},"executionMode":{"type":"string","enum":["AI_ONLY","AI_WITH_HITL"]},"hasFinalNote":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"finalNote":{"type":["string","null"]}},"required":["id","organizationId","status","patientId","appointmentId","templateId","template","audioDurationSeconds","executionMode","hasFinalNote","createdAt","updatedAt","finalNote"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"RECORDING","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","templateId":"00000000-0000-4000-8000-000000000001","template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example scribe_job","specialty":"example-specialty"},"audioDurationSeconds":1,"executionMode":"AI_ONLY","hasFinalNote":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","finalNote":"Example scribe_job note"},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Scribe job not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"put":{"operationId":"updateScribeJob","summary":"Update scribe job","description":"Updates safe public fields on an organization-scoped scribe job, including status, finalNote, templateId, audioDurationSeconds, and executionMode.\n\n### When to use\nUse this endpoint to synchronize safe job metadata or approved note content from an integration back into the local QuickRCM scribe job.\n\n### Before calling\nAuthenticate with a Scribe write-capable API key. Retrieve the current job, decide the minimal fields to update, and ensure any replacement templateId belongs to the authenticated organization. Confirm that finalNote content is approved for this workflow before sending it.\n\n### Request guidance\nAt least one update field must be provided. status must use the public scribe status enum, finalNote is nullable and capped at 100000 characters, audioDurationSeconds must be a non-negative integer or null, and executionMode must be `AI_ONLY` or `AI_WITH_HITL`. Do not send raw transcripts, audio URLs, signed URL secrets, vendor payloads, credentials, or unreviewed PHI.\n\n### Request notes\n- Send only the fields being changed.\n- finalNote can contain PHI and must use synthetic placeholder content in documentation examples.\n- templateId can be set to null in the OpenAPI schema, but a non-null replacement must be organization-scoped.\n\n### Response semantics\nHTTP 200 returns data.job and meta.organizationId. The response can include finalNote but does not return raw transcripts, audio URLs, signed URLs, storage references, or vendor payloads.\n\n### Response notes\n- The returned job reflects local QuickRCM scribe state.\n- No raw transcript, audio URL, storage reference, or vendor response is returned.\n- hasFinalNote should align with whether finalNote is present, but callers should rely on the returned fields rather than inferring hidden content.\n\n### Errors and retries\nTreat 400 as an empty or invalid update body, 404 as a missing or wrong-organization job or template reference, 401/403 as credential or tenant authorization failure, and 429 as a backoff signal. Avoid blind retries when the body changes clinical note content.\n\n### Error notes\n- 400 can indicate that no update fields were provided.\n- 404 can indicate a wrong-organization jobId or referenced templateId.\n- Do not retry clinical note updates without checking whether the prior attempt succeeded.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path","description":"Required scribe job identifier in the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["RECORDING","UPLOADING","TRANSCRIBING","GENERATING_NOTE","COMPLETED","ATTESTED","FAILED"],"description":"Local scribe job status. Valid values are `RECORDING`, `UPLOADING`, `TRANSCRIBING`, `GENERATING_NOTE`, `COMPLETED`, `ATTESTED`, and `FAILED`."},"finalNote":{"type":["string","null"],"maxLength":100000,"description":"Generated or reviewed clinical note text. Treat as PHI and avoid real content in examples and logs. Maximum length is 100000 characters."},"templateId":{"type":["string","null"],"minLength":1,"description":"Nullable replacement organization-scoped template identifier."},"audioDurationSeconds":{"type":["integer","null"],"minimum":0,"description":"Nullable non-negative audio duration in whole seconds."},"executionMode":{"type":"string","enum":["AI_ONLY","AI_WITH_HITL"],"description":"Scribe execution mode. Valid values are `AI_ONLY` and `AI_WITH_HITL`."}}},"example":{"status":"RECORDING","finalNote":"Example scribe_job note","templateId":"00000000-0000-4000-8000-000000000001","audioDurationSeconds":1,"executionMode":"AI_ONLY"}}},"description":"At least one update field must be provided. status must use the public scribe status enum, finalNote is nullable and capped at 100000 characters, audioDurationSeconds must be a non-negative integer or null, and executionMode must be `AI_ONLY` or `AI_WITH_HITL`. Do not send raw transcripts, audio URLs, signed URL secrets, vendor payloads, credentials, or unreviewed PHI."},"responses":{"200":{"description":"Updated organization-scoped scribe job.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["RECORDING","UPLOADING","TRANSCRIBING","GENERATING_NOTE","COMPLETED","ATTESTED","FAILED"]},"patientId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"templateId":{"type":["string","null"]},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"specialty":{"type":["string","null"]}},"required":["id","name","specialty"]},"audioDurationSeconds":{"type":["integer","null"]},"executionMode":{"type":"string","enum":["AI_ONLY","AI_WITH_HITL"]},"hasFinalNote":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"finalNote":{"type":["string","null"]}},"required":["id","organizationId","status","patientId","appointmentId","templateId","template","audioDurationSeconds","executionMode","hasFinalNote","createdAt","updatedAt","finalNote"]}},"required":["job"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"RECORDING","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","templateId":"00000000-0000-4000-8000-000000000001","template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example scribe_job","specialty":"example-specialty"},"audioDurationSeconds":1,"executionMode":"AI_ONLY","hasFinalNote":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","finalNote":"Example scribe_job note"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Scribe job or template not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/scribe/jobs/{jobId}/files":{"post":{"operationId":"attachScribeJobFile","summary":"Attach scribe job file","description":"Records metadata for an already-uploaded organization-scoped scribe audio file, links that audio reference to the job, sets the job status to `UPLOADING`, and returns sanitized file and job metadata.\n\n### When to use\nUse this endpoint when the scribe job already exists and the integration has completed file upload through a separate trusted upload path. Follow with queueScribeJobProcessing when the job should be processed.\n\n### Before calling\nAuthenticate with a Scribe write-capable API key. Ensure the target job belongs to the API-key organization and the provided storage reference is organization-scoped.\n\n### Request guidance\n`fileName`, `fileType`, `fileSize`, and `s3Key` are required. `fileName` and `fileType` are capped at 255 characters. `fileSize` must be an integer from 1 byte through 104857600 bytes. `s3Key` is capped at 2048 characters and must not contain relative path segments. Optional `fileUrl` is capped at 2048 characters. Do not send file bytes in this request.\n\n### Request notes\n- This endpoint does not upload file bytes or create a presigned upload URL.\n- If fileUrl is supplied, implementation stores fileUrl as the job audio reference; otherwise it stores the submitted storage reference.\n- Use only synthetic placeholders in docs for storage references.\n\n### Response semantics\nHTTP 200 returns `data.status=ATTACHED`, `externalUploadSkipped=true`, a sanitized file object, and the updated job. Public responses do not echo fileUrl, s3Key, signed URLs, or any raw audio content.\n\n### Response notes\n- externalUploadSkipped is always true for the public wrapper.\n- file includes id, organizationId, filename, mimeType, and sizeBytes.\n- The returned job can include finalNote, but attach responses normally only update file linkage and status.\n\n### Errors and retries\nTreat 400 as invalid metadata or storage reference shape, 404 as a missing or wrong-organization job, 401/403 as credential or tenant authorization failure, and 429 as a backoff signal. Avoid retrying blindly if the first request may already have created the file metadata record.\n\n### Error notes\n- 400 can indicate fileName/fileType length violations, fileSize outside 1 to 104857600, an overlong storage reference, or a relative path segment in the storage reference.\n- 404 can mean jobId is outside the authenticated organization.\n- Do not surface raw storage keys or signed URLs in client-facing errors.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path","description":"Required scribe job identifier in the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":255,"description":"Display filename for the already-uploaded audio file. Required, trimmed, maximum 255 characters."},"fileType":{"type":"string","minLength":1,"maxLength":255,"description":"MIME type or file type label. Required, trimmed, maximum 255 characters."},"fileSize":{"type":"integer","minimum":1,"maximum":104857600,"description":"File size in bytes. Required integer from 1 through 104857600."},"s3Key":{"type":"string","minLength":1,"maxLength":2048,"description":"Required organization-scoped storage reference. Maximum 2048 characters and cannot contain `..`; use only synthetic placeholders in examples."},"fileUrl":{"type":"string","minLength":1,"maxLength":2048,"description":"Optional organization-authorized file URL or reference. Maximum 2048 characters and not returned in public API responses."}},"required":["fileName","fileType","fileSize","s3Key"]},"example":{"fileName":"Example attach_scribe_job_file","fileType":"example-filetype","fileSize":1,"s3Key":"example-s3key","fileUrl":"https://example.quickintell.com/resource"}}},"description":"`fileName`, `fileType`, `fileSize`, and `s3Key` are required. `fileName` and `fileType` are capped at 255 characters. `fileSize` must be an integer from 1 byte through 104857600 bytes. `s3Key` is capped at 2048 characters and must not contain relative path segments. Optional `fileUrl` is capped at 2048 characters. Do not send file bytes in this request."},"responses":{"200":{"description":"Scribe audio file attached to the organization-scoped job.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["ATTACHED"]},"externalUploadSkipped":{"type":"boolean","enum":[true]},"file":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"filename":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer"}},"required":["id","organizationId","filename","mimeType","sizeBytes"]},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["RECORDING","UPLOADING","TRANSCRIBING","GENERATING_NOTE","COMPLETED","ATTESTED","FAILED"]},"patientId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"templateId":{"type":["string","null"]},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"specialty":{"type":["string","null"]}},"required":["id","name","specialty"]},"audioDurationSeconds":{"type":["integer","null"]},"executionMode":{"type":"string","enum":["AI_ONLY","AI_WITH_HITL"]},"hasFinalNote":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"finalNote":{"type":["string","null"]}},"required":["id","organizationId","status","patientId","appointmentId","templateId","template","audioDurationSeconds","executionMode","hasFinalNote","createdAt","updatedAt","finalNote"]}},"required":["status","externalUploadSkipped","file","job"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"status":"ATTACHED","externalUploadSkipped":true,"file":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","filename":"Example attach_scribe_job_file","mimeType":"example-mimetype","sizeBytes":1},"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"RECORDING","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","templateId":"00000000-0000-4000-8000-000000000001","template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example attach_scribe_job_file","specialty":"example-specialty"},"audioDurationSeconds":1,"executionMode":"AI_ONLY","hasFinalNote":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","finalNote":"Example attach_scribe_job_file note"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Scribe job not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/scribe/jobs/{jobId}/attest":{"post":{"operationId":"attestScribeJob","summary":"Attest scribe job","description":"Marks a completed or already-attested organization-scoped scribe job as `ATTESTED`, optionally recording an attestation note, and returns sanitized job metadata.\n\n### When to use\nUse this endpoint after a provider or authorized workflow has reviewed a completed note and wants to mark the local Scribe job as attested.\n\n### Before calling\nAuthenticate with a Scribe write-capable API key. Retrieve the job and verify it is in `COMPLETED` or `ATTESTED` state. Confirm any attestation note is approved for storage.\n\n### Request guidance\njobId is required in the path. The optional attestationNote is capped at 10000 characters. Do not include real PHI, transcript text, signatures, identity documents, credentials, tokens, storage references, or vendor payloads in examples.\n\n### Request notes\n- The implementation accepts jobs already in ATTESTED state as well as COMPLETED.\n- attestationNote is optional and should be concise.\n- Do not document this endpoint as validating coding, clinical correctness, or legal signature requirements.\n\n### Response semantics\nHTTP 200 returns data.job and meta.organizationId. The returned job status is `ATTESTED`. The public response can include finalNote but does not expose raw transcript text, audio references, attestedById, attestedAt, signatures, or identity proofing material.\n\n### Response notes\n- The returned job object follows the same public job schema used by get and update.\n- finalNote remains PHI-sensitive if present.\n- No raw audio, transcript, or attestation identity material is returned.\n\n### Errors and retries\nTreat 400 as invalid input or an attempt to attest a job outside the accepted states, 404 as a missing or wrong-organization job, 401/403 as credential or tenant authorization failure, and 429 as a backoff signal. Avoid describing this endpoint as legal e-signature capture or external identity proofing.\n\n### Error notes\n- 400 can indicate the job is not in COMPLETED or ATTESTED state.\n- 404 can mean jobId is outside the authenticated organization.\n- 429 should be retried with backoff.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path","description":"Required scribe job identifier in the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"attestationNote":{"type":"string","maxLength":10000,"description":"Optional note supplied during attestation, capped at 10000 characters. Avoid real PHI in public examples."}}},"example":{"attestationNote":"Example attest_scribe_job note"}}},"description":"jobId is required in the path. The optional attestationNote is capped at 10000 characters. Do not include real PHI, transcript text, signatures, identity documents, credentials, tokens, storage references, or vendor payloads in examples."},"responses":{"200":{"description":"Attested organization-scoped scribe job.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["RECORDING","UPLOADING","TRANSCRIBING","GENERATING_NOTE","COMPLETED","ATTESTED","FAILED"]},"patientId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"templateId":{"type":["string","null"]},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"specialty":{"type":["string","null"]}},"required":["id","name","specialty"]},"audioDurationSeconds":{"type":["integer","null"]},"executionMode":{"type":"string","enum":["AI_ONLY","AI_WITH_HITL"]},"hasFinalNote":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"finalNote":{"type":["string","null"]}},"required":["id","organizationId","status","patientId","appointmentId","templateId","template","audioDurationSeconds","executionMode","hasFinalNote","createdAt","updatedAt","finalNote"]}},"required":["job"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"RECORDING","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","templateId":"00000000-0000-4000-8000-000000000001","template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example attest_scribe_job","specialty":"example-specialty"},"audioDurationSeconds":1,"executionMode":"AI_ONLY","hasFinalNote":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","finalNote":"Example attest_scribe_job note"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Scribe job not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/scribe/jobs/{jobId}/process":{"post":{"operationId":"queueScribeJobProcessing","summary":"Queue scribe job processing","description":"Queues asynchronous processing for an existing organization-scoped scribe job that already has an attached audio reference, updates local status to `TRANSCRIBING`, and returns HTTP 202 queue acknowledgement.\n\n### When to use\nUse this endpoint after attachScribeJobFile or another approved workflow has attached audio to an existing job. Do not use it after createScribeJob unless a retry or requeue is explicitly needed, because createScribeJob already attempts to enqueue processing.\n\n### Before calling\nAuthenticate with a Scribe write-capable API key. Confirm the job belongs to the authenticated organization and has an attached audio reference.\n\n### Request guidance\n`queueOnly` is required and must be true. `language` defaults to `en` and is capped at 20 characters. `annotate` defaults to false. Public API processing requests only enqueue work and never run clinical processing inline.\n\n### Request notes\n- queueOnly must be true; public API callers cannot trigger inline processing.\n- A job without an audio reference returns 400.\n- Use bounded polling on getScribeJob or listScribeJobs after queue acceptance.\n\n### Response semantics\nHTTP 202 returns `data.status=QUEUED`, `data.queueOnly=true`, and the updated job. After successful queueing, the returned job status is `TRANSCRIBING`. The response does not include the audio reference, raw transcript, signed URLs, storage references, or vendor payloads.\n\n### Response notes\n- data.status is queue acknowledgement and should be `QUEUED`.\n- data.job.status is the local job lifecycle status and should be `TRANSCRIBING` after successful queueing.\n- HTTP 202 means asynchronous acceptance, not completed transcription or note generation.\n\n### Errors and retries\nTreat 400 as invalid queueOnly input or a job with no attached audio reference, 404 as a missing or wrong-organization job, 401/403 as credential or tenant authorization failure, 429 as a backoff signal, and 5xx as a server or queueing failure. Runtime handler evidence shows a 503 queue-failure path, but generated OpenAPI currently documents 500 rather than an explicit 503.\n\n### Error notes\n- 400 can indicate missing/false queueOnly or that the selected job has no attached audio file.\n- The queue-failure path is runtime-observed as 503 even though generated OpenAPI currently rolls unexpected server failures into 500.\n- 429 should slow requeue attempts and polling.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path","description":"Required scribe job identifier in the authenticated organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"description":"Required literal true flag. Public API processing queues work and does not run local clinical processing inline."},"language":{"type":"string","minLength":1,"maxLength":20,"default":"en","description":"Language hint for transcription and note generation. Defaults to `en` and is capped at 20 characters."},"annotate":{"type":"boolean","default":false,"description":"Boolean processing hint. Defaults to false."}},"required":["queueOnly"]},"example":{"queueOnly":true,"language":"en","annotate":false}}},"description":"`queueOnly` is required and must be true. `language` defaults to `en` and is capped at 20 characters. `annotate` defaults to false. Public API processing requests only enqueue work and never run clinical processing inline."},"responses":{"202":{"description":"Scribe processing was queued.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["QUEUED"]},"queueOnly":{"type":"boolean","enum":[true]},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["RECORDING","UPLOADING","TRANSCRIBING","GENERATING_NOTE","COMPLETED","ATTESTED","FAILED"]},"patientId":{"type":["string","null"]},"appointmentId":{"type":["string","null"]},"templateId":{"type":["string","null"]},"template":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"specialty":{"type":["string","null"]}},"required":["id","name","specialty"]},"audioDurationSeconds":{"type":["integer","null"]},"executionMode":{"type":"string","enum":["AI_ONLY","AI_WITH_HITL"]},"hasFinalNote":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"finalNote":{"type":["string","null"]}},"required":["id","organizationId","status","patientId","appointmentId","templateId","template","audioDurationSeconds","executionMode","hasFinalNote","createdAt","updatedAt","finalNote"]}},"required":["status","queueOnly","job"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"status":"QUEUED","queueOnly":true,"job":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","status":"RECORDING","patientId":"00000000-0000-4000-8000-000000000001","appointmentId":"00000000-0000-4000-8000-000000000001","templateId":"00000000-0000-4000-8000-000000000001","template":{"id":"00000000-0000-4000-8000-000000000001","name":"Example scribe_job_processing","specialty":"example-specialty"},"audioDurationSeconds":1,"executionMode":"AI_ONLY","hasFinalNote":true,"createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z","finalNote":"Example scribe_job_processing note"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Scribe job not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/scribe/templates":{"get":{"operationId":"listScribeTemplates","summary":"List scribe templates","description":"Returns paginated organization-scoped reusable scribe templates available for public API job creation.\n\n### When to use\nUse this endpoint before creating Scribe jobs, before filtering jobs by templateId, or to let an integration choose an existing template instead of creating duplicates.\n\n### Before calling\nAuthenticate with a Scribe read-capable API key. Decide whether to filter by specialty.\n\n### Request guidance\n`page` defaults to 1 and is capped at 10000. `pageSize` defaults to 25 and is capped at 100. `specialty` is optional, trimmed, and capped at 100 characters. Do not send tenant fields; tenant context comes from the API key.\n\n### Request notes\n- Use the specialty filter to reduce prompt/template search results.\n- Read-capable credentials can list templates; write-capable credentials are only needed to create or update templates.\n- Do not use this endpoint to store or retrieve patient-specific documentation.\n\n### Response semantics\nHTTP 200 returns `data.templates`, pagination fields, and `meta.organizationId`. Each template includes id, organizationId, name, template, specialty, isDefault, and createdAt. Template text is reusable prompt configuration, not patient-specific note content.\n\n### Response notes\n- createdAt can be null in the public template schema.\n- The public template field contains stored prompt text.\n- No job, transcript, audio reference, or final note is returned.\n\n### Errors and retries\nTreat 400 as invalid pagination or specialty filter input, 401 as missing or invalid bearer credentials, 403 as organization access denial, and 429 as a backoff signal. Retry transient 5xx with bounded client retries.\n\n### Error notes\n- 400 can indicate pagination bounds or specialty length violations.\n- 429 should be retried with backoff.\n- 403 means the authenticated caller cannot access the selected organization context.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":10000,"default":1},"required":false,"name":"page","in":"query","description":"One-based result page. Defaults to 1 and cannot exceed 10000."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"pageSize","in":"query","description":"Maximum number of templates to return. Defaults to 25 and cannot exceed 100."},{"schema":{"type":"string","minLength":1,"maxLength":100},"required":false,"name":"specialty","in":"query","description":"Optional specialty label filter, capped at 100 characters."}],"responses":{"200":{"description":"Scribe templates for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"template":{"type":"string"},"specialty":{"type":["string","null"]},"isDefault":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","name","template","specialty","isDefault","createdAt"]}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pageSize":{"type":"integer","minimum":1},"totalPages":{"type":"integer","minimum":0}},"required":["templates","total","page","pageSize","totalPages"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"templates":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example scribe_template","template":"example-template","specialty":"example-specialty","isDefault":true,"createdAt":"2026-06-08T10:15:30Z"}],"total":1,"page":1,"pageSize":1,"totalPages":1},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createScribeTemplate","summary":"Create scribe template","description":"Creates an organization-scoped scribe template for public API job creation, storing reusable prompt text from `structurePrompt` when supplied or from `template` otherwise.\n\n### When to use\nUse this endpoint when an integration needs to define reusable note structure or prompting configuration before creating scribe jobs.\n\n### Before calling\nAuthenticate with a Scribe write-capable API key. Choose a tenant-local template name and decide whether to send `template` or `structurePrompt`. The request requires name plus at least one of template or structurePrompt.\n\n### Request guidance\n`name` is required and capped at 200 characters. `template` and `structurePrompt` are each capped at 10000 characters, `specialty` is nullable and capped at 100 characters, and `isDefault` defaults to false. Keep template content generic and do not include real patient details, transcripts, credentials, tokens, storage references, or vendor payloads.\n\n### Request notes\n- The endpoint requires template or structurePrompt.\n- If both template and structurePrompt are supplied, implementation stores structurePrompt.\n- Template prompts should be reusable configuration, not patient-specific note content.\n- isDefault defaults to false when omitted.\n\n### Response semantics\nHTTP 201 returns data.template and meta.organizationId. The response template object includes id, organizationId, name, template, specialty, isDefault, and createdAt. It does not return structurePrompt as a distinct field; the stored prompt is returned as `template`.\n\n### Response notes\n- The response returns the created template object under data.template.\n- structurePrompt is not returned as a separate field in the OpenAPI response schema.\n- No scribe job, transcript, audio URL, or final note is created by this endpoint.\n\n### Errors and retries\nTreat 400 as invalid template input, including missing template or structurePrompt content, 401/403 as credential or tenant authorization failure, and 429 as a backoff signal. Avoid duplicate template creation in client retries.\n\n### Error notes\n- 400 can indicate missing template or structurePrompt content or field length violations.\n- Retried POST calls can create duplicate templates unless the client deduplicates.\n- 429 should be retried with backoff.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Required template display name, capped at 200 characters."},"template":{"type":"string","minLength":1,"maxLength":10000,"description":"Reusable scribe template text, capped at 10000 characters. Used when structurePrompt is absent."},"structurePrompt":{"type":"string","minLength":1,"maxLength":10000,"description":"Reusable structure prompt for generated note organization, capped at 10000 characters. Stored preferentially when supplied and returned through the public `template` response field."},"specialty":{"type":["string","null"],"minLength":1,"maxLength":100,"description":"Optional specialty label for filtering and display, capped at 100 characters."},"isDefault":{"type":"boolean","default":false,"description":"Boolean flag requesting default-template behavior. Defaults to false."}},"required":["name"]},"example":{"name":"Example scribe_template","template":"example-template","structurePrompt":"example-structureprompt","specialty":"example-specialty","isDefault":false}}},"description":"`name` is required and capped at 200 characters. `template` and `structurePrompt` are each capped at 10000 characters, `specialty` is nullable and capped at 100 characters, and `isDefault` defaults to false. Keep template content generic and do not include real patient details, transcripts, credentials, tokens, storage references, or vendor payloads."},"responses":{"201":{"description":"Created organization-scoped scribe template.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"template":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"template":{"type":"string"},"specialty":{"type":["string","null"]},"isDefault":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","name","template","specialty","isDefault","createdAt"]}},"required":["template"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"template":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example scribe_template","template":"example-template","specialty":"example-specialty","isDefault":true,"createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/scribe/templates/{templateId}":{"put":{"operationId":"updateScribeTemplate","summary":"Update scribe template","description":"Updates an organization-scoped scribe template, including reusable prompt text from `structurePrompt` when supplied or from `template` otherwise.\n\n### When to use\nUse this endpoint to revise reusable Scribe template configuration, change the specialty label, or update default-template behavior.\n\n### Before calling\nAuthenticate with a Scribe write-capable API key. Locate the template through listScribeTemplates and prepare the minimal set of fields to update. Confirm the template belongs to the authenticated organization.\n\n### Request guidance\ntemplateId is required in the path. At least one body field must be supplied. name is capped at 200 characters; template and structurePrompt are each capped at 10000 characters; specialty is nullable and capped at 100 characters. Do not include real patient-specific text, transcripts, credentials, tokens, storage references, or vendor payloads in template content.\n\n### Request notes\n- Send only fields that need to change.\n- If both template and structurePrompt are supplied, implementation stores structurePrompt.\n- structurePrompt may be accepted in the request but is not returned as a separate response field.\n\n### Response semantics\nHTTP 200 returns data.template and meta.organizationId. The response template object includes id, organizationId, name, template, specialty, isDefault, and createdAt. It does not expose structurePrompt as a distinct response field; the stored prompt is returned as `template`.\n\n### Response notes\n- The returned template is local organization configuration.\n- Changing a template does not itself create or reprocess scribe jobs.\n- Template text should remain patient-neutral in public examples.\n\n### Errors and retries\nTreat 400 as an empty or invalid update body, 404 as a missing or wrong-organization template, 401/403 as credential or tenant authorization failure, and 429 as a backoff signal. Do not retry blindly if concurrent template edits are possible.\n\n### Error notes\n- 400 can indicate no update fields or field length violations.\n- 404 can mean templateId is outside the authenticated organization.\n- 429 should be retried with backoff rather than rapid repeated updates.\n","tags":["Scribe"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"templateId","in":"path","description":"Required organization-scoped scribe template identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Template display name, capped at 200 characters."},"template":{"type":"string","minLength":1,"maxLength":10000,"description":"Reusable scribe template text, capped at 10000 characters. Used when structurePrompt is absent."},"structurePrompt":{"type":"string","minLength":1,"maxLength":10000,"description":"Reusable prompt for note structure, capped at 10000 characters. Stored preferentially when supplied and returned through the public `template` response field."},"specialty":{"type":["string","null"],"minLength":1,"maxLength":100,"description":"Optional specialty label for filtering and display, capped at 100 characters."},"isDefault":{"type":"boolean","description":"Boolean flag controlling default-template behavior where supported."}}},"example":{"name":"Example scribe_template","template":"example-template","structurePrompt":"example-structureprompt","specialty":"example-specialty","isDefault":true}}},"description":"templateId is required in the path. At least one body field must be supplied. name is capped at 200 characters; template and structurePrompt are each capped at 10000 characters; specialty is nullable and capped at 100 characters. Do not include real patient-specific text, transcripts, credentials, tokens, storage references, or vendor payloads in template content."},"responses":{"200":{"description":"Updated organization-scoped scribe template.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"template":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"template":{"type":"string"},"specialty":{"type":["string","null"]},"isDefault":{"type":"boolean"},"createdAt":{"type":["string","null"],"format":"date-time"}},"required":["id","organizationId","name","template","specialty","isDefault","createdAt"]}},"required":["template"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"template":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","name":"Example scribe_template","template":"example-template","specialty":"example-specialty","isDefault":true,"createdAt":"2026-06-08T10:15:30Z"}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Organization access denied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Scribe template not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/sftp/files/{fileId}/submit":{"post":{"operationId":"submitEdiFileToSftp","summary":"Submit EDI file to SFTP","description":"Validates or locally queues an organization-owned Electronic Data Interchange (EDI) file for a Secure File Transfer Protocol (SFTP) submission workflow while explicitly skipping live SFTP upload from the public API handler.\n\n### When to use\nUse this endpoint after an EDI file already exists in QuickRCM and an integration needs either a no-side-effect readiness check or a local task queued for later internal handling.\n\n### Before calling\nFor public API callers, authenticate with a tenant-scoped bearer API key that has `sftp:write` scope. Resolve the QuickRCM `fileId` for the EDI file inside that API key's organization. Decide whether this call is `validateOnly` or `queueOnly`; the public handler rejects requests that choose neither mode.\n\n### Request guidance\n`fileId` is the required path parameter. The request body supports `validateOnly`, `queueOnly`, and optional `externalSubmissionEnabled`. Set `validateOnly: true` for a readiness check with no file update or task creation. Set `queueOnly: true` to mark the file `QUEUED` and create a local task. `externalSubmissionEnabled` can only be `false`; do not document `true` as supported. Prefer sending exactly one of `validateOnly` or `queueOnly`; current handler behavior returns the validate-only response when both are true. No public `organizationId` or `idempotencyKey` field is declared for this operation.\n\n### Request notes\n- Do not send `organizationId`; the bearer API key selects the organization for the public request.\n- Do not include raw EDI content, S3 keys, credentials, payer portal secrets, or SFTP connection details in the request.\n- `validateOnly: true` has no file update or task creation side effect.\n- `queueOnly: true` is local queueing only, not external SFTP delivery.\n- `externalSubmissionEnabled` is an explicit false-only guardrail for public examples.\n- No `idempotencyKey` is accepted by the documented public schema; clients should re-read state after ambiguous queue attempts.\n\n### Response semantics\nHTTP 200 means the file belongs to the authenticated organization and is eligible for public safe-mode processing, but no local queue task or SFTP upload was created. HTTP 202 means QuickRCM updated the organization-owned file to `QUEUED` and created a local task, with `externalSubmissionSkipped: true`. Neither response proves an external SFTP upload, payer receipt, clearinghouse acceptance, or downstream EDI response.\n\n### Response notes\n- `data.externalSubmissionSkipped` is always `true` for documented public success responses.\n- `data.taskId` appears only in the 202 queue-only response.\n- `meta.organizationId` echoes the authenticated tenant context; it is not a request selector.\n- Success responses are sanitized workflow metadata and do not contain raw EDI, S3 storage keys, filenames, payer payloads, credentials, or API keys.\n\n### Errors and retries\nTreat 400 as an invalid body or missing safe-mode selection, 401 as missing or invalid public bearer API credentials, 403 as missing `sftp:write` scope or authorization failure, 404 as a file that does not belong to the API key organization or does not exist, 409 as an ineligible file state such as already queued or already submitted, and 429 as a backoff signal. The public schema has no idempotency key. After an ambiguous timeout or 5xx from a `queueOnly` request, re-check local file/task state before retrying; a retry may legitimately return 409 if the first attempt already moved the file to `QUEUED`.\n\n### Error notes\n- 400 can mean the request did not set either `validateOnly` or `queueOnly`.\n- 403 can mean the public API key lacks `sftp:write` scope before file data is read.\n- 404 should be documented without distinguishing missing files from wrong-organization files.\n- 409 indicates the file is not eligible for this public safe-mode submission flow, including already queued or already submitted states.\n- A retry after an ambiguous queue-only failure may return 409 because the previous attempt already queued the file; do not treat that as proof of duplicate task creation.\n- 429 should be retried with exponential backoff rather than tight polling.\n","tags":["SFTP EDI"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"fileId","in":"path","description":"QuickRCM File identifier in the path. The handler looks it up with both `id` and the organization selected by the public bearer API key."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","default":false,"description":"Safe-mode request flag. When true, the handler checks file ownership and eligibility and returns `mode: VALIDATE_ONLY` without updating the file, creating a task, or uploading to SFTP."},"queueOnly":{"type":"boolean","default":false,"description":"Safe-mode request flag. When true and `validateOnly` is not true, the handler marks the file `QUEUED`, creates a local task, and returns HTTP 202 with `mode: QUEUE_ONLY`."},"externalSubmissionEnabled":{"type":"boolean","enum":[false],"description":"False-only public guardrail. The OpenAPI schema allows only `false`; live SFTP upload is not enabled through this public endpoint."}},"example":{"validateOnly":true,"queueOnly":false,"externalSubmissionEnabled":false}},"example":{"validateOnly":true,"queueOnly":false,"externalSubmissionEnabled":false}}},"description":"`fileId` is the required path parameter. The request body supports `validateOnly`, `queueOnly`, and optional `externalSubmissionEnabled`. Set `validateOnly: true` for a readiness check with no file update or task creation. Set `queueOnly: true` to mark the file `QUEUED` and create a local task. `externalSubmissionEnabled` can only be `false`; do not document `true` as supported. Prefer sending exactly one of `validateOnly` or `queueOnly`; current handler behavior returns the validate-only response when both are true. No public `organizationId` or `idempotencyKey` field is declared for this operation."},"responses":{"200":{"description":"EDI file validated without side effects","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"fileId":{"type":"string"},"status":{"type":"string","enum":["VALIDATED"]},"mode":{"type":"string","enum":["VALIDATE_ONLY"]},"externalSubmissionSkipped":{"type":"boolean","enum":[true]}},"required":["fileId","status","mode","externalSubmissionSkipped"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"fileId":"00000000-0000-4000-8000-000000000001","status":"VALIDATED","mode":"VALIDATE_ONLY","externalSubmissionSkipped":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"202":{"description":"EDI file queued locally without live SFTP upload","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"fileId":{"type":"string"},"status":{"type":"string","enum":["QUEUED"]},"mode":{"type":"string","enum":["QUEUE_ONLY"]},"taskId":{"type":"string"},"externalSubmissionSkipped":{"type":"boolean","enum":[true]}},"required":["fileId","status","mode","taskId","externalSubmissionSkipped"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"fileId":"00000000-0000-4000-8000-000000000001","status":"QUEUED","mode":"QUEUE_ONLY","taskId":"00000000-0000-4000-8000-000000000001","externalSubmissionSkipped":true},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"EDI file not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"409":{"description":"EDI file is not eligible for public SFTP submission","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource conflict","statusCode":409}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/overview":{"get":{"operationId":"getSpecialtyBillingOverview","summary":"Get specialty billing overview","description":"Returns aggregate case counts and revenue totals for the authenticated organization across anesthesia, ASC, DME, laboratory, and behavioral-health specialty billing records.\n\n### When to use\nUse this endpoint to build an external Specialty Billing summary card, reconcile module volumes, or monitor aggregate specialty revenue without reading individual case records.\n\n### Before calling\nAuthenticate with `specialty-billing:read` or `specialty-billing:write`. Choose optional `dateFrom` and `dateTo` filters when you need a bounded reporting window.\n\n### Request guidance\n`dateFrom` and `dateTo` are optional ISO date or datetime strings. The filters apply to module-specific service/order dates: anesthesia and behavioral health use date of service, ASC uses scheduled date, and DME/laboratory use order date. Do not send an `organizationId` query parameter; the bearer credential selects the organization.\n\n### Request notes\n- No request body is declared.\n- Use bounded date filters for dashboard refreshes instead of broad repeated polling.\n- The endpoint returns aggregate metrics only, not individual patients, claims, or episodes.\n\n### Response semantics\nHTTP 200 returns `totalCases`, `totalRevenue`, and per-module `caseCount` plus `totalRevenue` for `anesthesia`, `asc`, `dme`, `laboratory`, and `behavioralHealth`. Money values are decimal strings. `meta.organizationId` echoes the authenticated organization.\n\n### Response notes\n- `totalRevenue` and module `totalRevenue` values are strings formatted from decimal-like sums.\n- The response does not prove payer adjudication or cash receipt; it summarizes local specialty billing records.\n- The response contains aggregate counts and totals only.\n\n### Errors and retries\nTreat 400 as invalid query input, 401/403 as credential, scope, or organization access failure, 429 as a backoff signal, and 5xx as transient only with bounded retries.\n\n### Error notes\n- 404 is part of the common generated error set, but overview failures are normally validation/auth/rate-limit/server issues.\n- Retry 429 and transient 5xx with backoff.\n- Do not retry malformed date values unchanged.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Optional inclusive start date filter for the module-specific service/order date."},"required":false,"description":"Optional inclusive start date filter for each module's service/order date field.","name":"dateFrom","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Optional inclusive end date filter for the module-specific service/order date."},"required":false,"description":"Optional inclusive end date filter for each module's service/order date field.","name":"dateTo","in":"query"}],"responses":{"200":{"description":"Specialty billing aggregate overview for the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"totalCases":{"type":"integer","minimum":0},"totalRevenue":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"modules":{"type":"object","properties":{"anesthesia":{"type":"object","properties":{"caseCount":{"type":"integer","minimum":0},"totalRevenue":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["caseCount","totalRevenue"]},"asc":{"type":"object","properties":{"caseCount":{"type":"integer","minimum":0},"totalRevenue":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["caseCount","totalRevenue"]},"dme":{"type":"object","properties":{"caseCount":{"type":"integer","minimum":0},"totalRevenue":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["caseCount","totalRevenue"]},"laboratory":{"type":"object","properties":{"caseCount":{"type":"integer","minimum":0},"totalRevenue":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["caseCount","totalRevenue"]},"behavioralHealth":{"type":"object","properties":{"caseCount":{"type":"integer","minimum":0},"totalRevenue":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["caseCount","totalRevenue"]}},"required":["anesthesia","asc","dme","laboratory","behavioralHealth"]}},"required":["totalCases","totalRevenue","modules"]},"meta":{"type":"object","properties":{"organizationId":{"type":"string"}},"required":["organizationId"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{"totalCases":1,"totalRevenue":"example-totalrevenue","modules":{"anesthesia":{"caseCount":1,"totalRevenue":"example-totalrevenue"},"asc":{"caseCount":1,"totalRevenue":"example-totalrevenue"},"dme":{"caseCount":1,"totalRevenue":"example-totalrevenue"},"laboratory":{"caseCount":1,"totalRevenue":"example-totalrevenue"},"behavioralHealth":{"caseCount":1,"totalRevenue":"example-totalrevenue"}}},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/episodes":{"post":{"operationId":"createHomeHealthEpisode","summary":"Create home-health episode","description":"Creates a local home-health episode, a draft certification, and two initial open payment periods for the authenticated organization.\n\n### When to use\nUse this when an integration needs to start home-health billing workflow state before generating an NOA, tracking authorizations, or previewing period-level claims.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Resolve required `patientId` and `facilityId` in QuickRCM for the same organization. Resolve optional payer, insurance, and provider identifiers before sending them.\n\n### Request guidance\n`patientId`, `facilityId`, `startOfCareDate`, and `primaryDiagnosisCode` are required. `lupaThreshold` must be an integer from 1 through 30 when supplied. Diagnosis codes are normalized to uppercase by the API. Do not include tenant hints or PHI-heavy notes.\n\n### Request notes\n- The API key selects the organization; body `organizationId`, `orgId`, and `signature` are not tenant selectors.\n- Optional patient insurance is checked against the same patient and organization.\n- `otherDiagnosisCodes` defaults to an empty array.\n\n### Response semantics\nHTTP 201 returns a workflow response with `externalRiskMode: SAFE_WRITE_DB_ONLY`, the created `episode`, and summarized payment periods using `id`, `episodeId`, `periodNumber`, date, and status fields. This is a local database write; it does not submit an NOA or claim.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` means local QuickRCM records were written.\n- The payment-period response is summarized with `periodNumber`, `periodStartDate`, `periodEndDate`, and local status fields; it is not a full billing ledger.\n- The episode starts as local status `ACTIVE` in the public API.\n\n### Errors and retries\nA 404 can mean the patient, facility, payer config, provider, or patient-insurance record did not resolve inside the authenticated organization. After a timeout, search or read local workflow state before creating another episode.\n\n### Error notes\n- 400 can indicate invalid dates or out-of-range `lupaThreshold`.\n- 404 hides missing and wrong-organization linked records.\n- Avoid blind retries after ambiguous success because duplicate episode workflow state may be created.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"Required QuickRCM patient identifier in the API-key organization."},"facilityId":{"type":"string","minLength":1,"description":"Required facility identifier in the API-key organization."},"payerConfigId":{"type":"string","minLength":1,"description":"Optional payer configuration identifier in the same organization."},"patientInsuranceId":{"type":"string","minLength":1,"description":"Optional patient insurance identifier for the same patient and organization."},"startOfCareDate":{"type":"string","minLength":1,"description":"Required ISO date or datetime for the home-health start of care."},"primaryDiagnosisCode":{"type":"string","minLength":1,"description":"Required primary diagnosis code; the API stores an uppercase normalized value."},"otherDiagnosisCodes":{"type":"array","items":{"type":"string","minLength":1},"default":[],"description":"Optional additional diagnosis codes; defaults to an empty array and is uppercased."},"certifyingProviderId":{"type":"string","minLength":1,"description":"Optional Provider identifier for the certifying clinician in the API-key organization."},"orderingProviderId":{"type":"string","minLength":1,"description":"Optional Provider identifier for the ordering clinician in the API-key organization."},"lupaThreshold":{"type":"integer","minimum":1,"maximum":30,"description":"Optional Low Utilization Payment Adjustment visit threshold from 1 through 30."}},"required":["patientId","facilityId","startOfCareDate","primaryDiagnosisCode"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","startOfCareDate":"2026-06-08","primaryDiagnosisCode":"example-primarydiagnosiscode","payerConfigId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","otherDiagnosisCodes":[],"certifyingProviderId":"00000000-0000-4000-8000-000000000001","orderingProviderId":"00000000-0000-4000-8000-000000000001","lupaThreshold":1}}},"description":"`patientId`, `facilityId`, `startOfCareDate`, and `primaryDiagnosisCode` are required. `lupaThreshold` must be an integer from 1 through 30 when supplied. Diagnosis codes are normalized to uppercase by the API. Do not include tenant hints or PHI-heavy notes."},"responses":{"201":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/episodes/{episodeId}":{"put":{"operationId":"updateHomeHealthEpisode","summary":"Update home-health episode","description":"Updates safe local fields on an organization-scoped home-health episode.\n\n### When to use\nUse this when an external system needs to change local episode lifecycle status, discharge date, diagnosis codes, payer/insurance references, or certifying/ordering provider references.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Use an `episodeId` obtained from the same organization. Resolve optional payer, insurance, and provider identifiers before updating them.\n\n### Request guidance\nThe schema accepts optional body fields. For current handler behavior, omitted or explicit null `dischargeDate` is written as null; send the current discharge date when it must be preserved. `status` must be `DRAFT`, `ACTIVE`, `DISCHARGED`, or `CANCELLED`. Nullable linked IDs are preserved when omitted and cleared when sent as null.\n\n### Request notes\n- The route uses PUT because the generated public API route set does not use PATCH.\n- If `patientInsuranceId` is supplied, it is checked against the episode's patient.\n- Diagnosis code fields are uppercased when stored.\n- Current implementation treats omitted `dischargeDate` the same as null on this PUT route; preserve-by-omission should not be assumed for that date field.\n\n### Response semantics\nHTTP 200 returns a workflow response with `externalRiskMode: SAFE_WRITE_DB_ONLY` and the updated local episode. No NOA, claim, clearinghouse, EHR, or payer side effect is performed.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` marks local persistence only.\n- The response data contains the updated episode object from the API.\n- No payment periods are regenerated by this endpoint.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant episode or linked reference. Re-read the episode after ambiguous timeouts before retrying to avoid overwriting newer local edits.\n\n### Error notes\n- 400 can indicate invalid enum or date values.\n- 404 can indicate wrong-organization identifiers.\n- Retry only after checking current episode state when a request may have succeeded.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"episodeId","in":"path","description":"HomeHealthEpisode identifier in the path; it must belong to the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["DRAFT","ACTIVE","DISCHARGED","CANCELLED"],"description":"Optional local episode status: DRAFT, ACTIVE, DISCHARGED, or CANCELLED."},"dischargeDate":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO discharge date/datetime. Current handler behavior writes null when this field is omitted or sent as null."},"primaryDiagnosisCode":{"type":"string","minLength":1,"description":"Optional replacement primary diagnosis code; the API stores the normalized uppercase value."},"otherDiagnosisCodes":{"type":"array","items":{"type":"string","minLength":1},"description":"Optional replacement array of additional diagnosis codes; supplied values are stored uppercase."},"payerConfigId":{"type":["string","null"],"minLength":1,"description":"Optional nullable same-organization payer config reference."},"patientInsuranceId":{"type":["string","null"],"minLength":1,"description":"Optional nullable patient insurance reference for the episode patient."},"certifyingProviderId":{"type":["string","null"],"minLength":1,"description":"Optional nullable Provider identifier for the certifying clinician. Null clears the local reference; non-null values must belong to the API-key organization."},"orderingProviderId":{"type":["string","null"],"minLength":1,"description":"Optional nullable Provider identifier for the ordering clinician. Null clears the local reference; non-null values must belong to the API-key organization."}}},"example":{"status":"DRAFT","dischargeDate":"2026-06-08","primaryDiagnosisCode":"example-primarydiagnosiscode","otherDiagnosisCodes":["example-otherdiagnosiscodes"],"payerConfigId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","certifyingProviderId":"00000000-0000-4000-8000-000000000001","orderingProviderId":"00000000-0000-4000-8000-000000000001"}}},"description":"The schema accepts optional body fields. For current handler behavior, omitted or explicit null `dischargeDate` is written as null; send the current discharge date when it must be preserved. `status` must be `DRAFT`, `ACTIVE`, `DISCHARGED`, or `CANCELLED`. Nullable linked IDs are preserved when omitted and cleared when sent as null."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/episodes/{episodeId}/noa":{"post":{"operationId":"generateHomeHealthNoa","summary":"Generate home-health NOA","description":"Validates a home-health Notice of Admission payload by default, or creates a local NOA record when `validateOnly` is explicitly false.\n\n### When to use\nUse this after creating or locating an episode to validate NOA readiness, or to create a local READY NOA record before queueing submission.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use an `episodeId` from the same organization. Decide whether you want validation-only behavior or a local NOA record.\n\n### Request guidance\n`effectiveDate` is optional and falls back to the episode start-of-care date when omitted. `validateOnly` defaults to true. Set `validateOnly: false` only when you intend to create a local NOA record; even then, no clearinghouse submission occurs.\n\n### Request notes\n- `validateOnly` is not a required false-to-create flag; it defaults to validation-only.\n- Creating a local NOA does not submit an 837I or call a clearinghouse.\n- The generated payload is local workflow metadata.\n\n### Response semantics\nValidation returns HTTP 200 with `externalRiskMode: VALIDATION_ONLY` and side effects set to false. Local NOA creation returns HTTP 201 with `externalRiskMode: SAFE_WRITE_DB_ONLY` and a READY NOA record with due date five days after the effective date.\n\n### Response notes\n- HTTP 200 means validation-only.\n- HTTP 201 means a local NOA record was created.\n- The response `externalRiskMode` distinguishes validation from local write behavior.\n\n### Errors and retries\nA 404 means the episode was not found in the authenticated organization. Do not retry invalid dates unchanged. After ambiguous creation, inspect local NOA state before retrying.\n\n### Error notes\n- 404 can indicate missing or wrong-tenant episode.\n- 400 can indicate invalid `effectiveDate`.\n- Avoid duplicate local NOA records after uncertain timeouts.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"episodeId","in":"path","description":"HomeHealthEpisode identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"effectiveDate":{"type":"string","minLength":1,"description":"Optional ISO date/datetime used for NOA effective date and due-date calculation."},"validateOnly":{"type":"boolean","default":true,"description":"Defaults to true; when true or omitted, validates only. Set false to create a local NOA without submitting it."}}},"example":{"effectiveDate":"2026-06-08","validateOnly":true}}},"description":"`effectiveDate` is optional and falls back to the episode start-of-care date when omitted. `validateOnly` defaults to true. Set `validateOnly: false` only when you intend to create a local NOA record; even then, no clearinghouse submission occurs."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"201":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/episodes/{episodeId}/noa/submit":{"post":{"operationId":"submitHomeHealthNoa","summary":"Queue home-health NOA submission","description":"Queues a local home-health NOA submission attempt and updates the local NOA to pending acknowledgement.\n\n### When to use\nUse this after a local NOA exists and an external integration wants QuickRCM to track queued submission state.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Use a same-organization `episodeId` and a `noaId` attached to that episode.\n\n### Request guidance\n`noaId` is required. `queueOnly` is fixed to true and defaults to true. `adapterName` defaults to `STEDI`, but this endpoint records a queued local attempt instead of invoking an adapter inline. `idempotencyKey` is stored as the local correlation id when supplied.\n\n### Request notes\n- `adapterName` is a local marker, not proof of a live Stedi or Availity call.\n- `idempotencyKey` should be a synthetic retry/correlation key, not PHI or a secret.\n- `queueOnly` must remain true.\n\n### Response semantics\nHTTP 202 returns `externalRiskMode: QUEUED_ONLY`, status `queued`, the episode/noa identifiers, and the created submission attempt. The local NOA is updated to `PENDING_ACK`.\n\n### Response notes\n- `QUEUED_ONLY` means accepted for local queue-style tracking.\n- The created attempt has submission method `837I` in the public API and is returned as a local attempt snapshot.\n- The attempt can include local request/response payload metadata from the NOA; examples must keep that metadata abbreviated and must not show raw EDI.\n\n### Errors and retries\nA 404 means the episode or NOA did not resolve in the same organization/episode scope. After timeouts, read NOA/submission-attempt state before retrying.\n\n### Error notes\n- 400 can indicate invalid body shape or queue flag.\n- 404 can indicate the NOA is not attached to the supplied episode.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"episodeId","in":"path","description":"HomeHealthEpisode identifier in the path; the NOA must be attached to this episode in the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"noaId":{"type":"string","minLength":1,"description":"Required HomeHealthNoa identifier scoped to the path episode and organization."},"queueOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; must be true for public submission requests."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":160,"description":"Optional local correlation id, up to 160 characters."},"adapterName":{"type":"string","minLength":1,"maxLength":80,"default":"STEDI","description":"Optional local adapter label, defaulting to STEDI."}},"required":["noaId"]},"example":{"noaId":"00000000-0000-4000-8000-000000000001","queueOnly":true,"idempotencyKey":"example-idempotencykey","adapterName":"STEDI"}}},"description":"`noaId` is required. `queueOnly` is fixed to true and defaults to true. `adapterName` defaults to `STEDI`, but this endpoint records a queued local attempt instead of invoking an adapter inline. `idempotencyKey` is stored as the local correlation id when supplied."},"responses":{"202":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/payment-periods/{paymentPeriodId}/claim-draft":{"post":{"operationId":"draftHomeHealthClaim","summary":"Preview home-health claim draft","description":"Validates and previews home-health claim-draft readiness for a local payment period.\n\n### When to use\nUse this before claim creation/submission workflows to confirm a payment period is available and identify the linked or caller-supplied claim id.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Use a payment period from the same organization.\n\n### Request guidance\n`validateOnly` is fixed to true and defaults to true. `claimId` is optional and returned as preview context when supplied; the endpoint does not verify claim creation or submit EDI.\n\n### Request notes\n- `validateOnly` must remain true.\n- No request body is needed unless passing an optional `claimId` preview marker.\n- This endpoint is validation-only even though it is a POST.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: VALIDATION_ONLY`, status `validated`, payment period id, preview claim id, and side effects showing no claim, EDI payload, or clearinghouse submission is created.\n\n### Response notes\n- `sideEffects.createsClaim` is false.\n- `sideEffects.createsEdiPayload` is false.\n- `sideEffects.submitsClearinghouse` is false.\n\n### Errors and retries\nA 404 means the payment period was not found in the authenticated organization. Retry only after correcting invalid identifiers or transient failures.\n\n### Error notes\n- 404 hides wrong-organization payment periods.\n- Do not present this endpoint as institutional claim generation.\n- Use submit endpoints only after a claim exists in local workflow state.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"paymentPeriodId","in":"path","description":"HomeHealthPaymentPeriod identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; validates and previews only."},"claimId":{"type":"string","minLength":1,"description":"Optional claim identifier to echo as preview context."}}},"example":{"validateOnly":true,"claimId":"00000000-0000-4000-8000-000000000001"}}},"description":"`validateOnly` is fixed to true and defaults to true. `claimId` is optional and returned as preview context when supplied; the endpoint does not verify claim creation or submit EDI."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/claims/{claimId}/submit":{"post":{"operationId":"submitHomeHealthClaim","summary":"Queue home-health claim submission","description":"Queues a local home-health institutional claim submission marker and writes a local claim status check.\n\n### When to use\nUse this when a home-health institutional claim already exists in QuickRCM and should be marked queued for downstream submission tracking.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Use a same-organization claim id that represents the home-health institutional claim workflow.\n\n### Request guidance\n`queueOnly` is fixed to true and defaults to true. `adapterName` defaults to `STEDI` as local metadata. `idempotencyKey` may be stored as `stediCorrelationId` when supplied but is not proof of a live Stedi submission.\n\n### Request notes\n- No raw 837I payload is accepted or returned.\n- `adapterName` is a local marker.\n- `idempotencyKey` should not contain PHI or secrets.\n\n### Response semantics\nHTTP 202 returns `externalRiskMode: QUEUED_ONLY`, status `queued`, `claimId`, and `adapterName`. The API can update the local claim to `QUEUED` and create a local `ClaimStatusCheck` with queued-only payload.\n\n### Response notes\n- `QUEUED_ONLY` means local queue/status state was recorded.\n- This endpoint does not return payer acceptance or adjudication.\n- Use the status endpoint to read latest local status markers.\n\n### Errors and retries\nA 404 means the claim was not found in the authenticated organization. After a timeout, check local claim status before retrying.\n\n### Error notes\n- 400 can indicate invalid queue flag or body shape.\n- 404 can indicate missing or wrong-tenant claim.\n- Retry 429 and transient 5xx with backoff.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"Claim identifier in the path; it must belong to the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; must be true for public submission requests."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":160,"description":"Optional local correlation id, up to 160 characters."},"adapterName":{"type":"string","minLength":1,"maxLength":80,"default":"STEDI","description":"Optional local adapter label, defaulting to STEDI."}}},"example":{"queueOnly":true,"idempotencyKey":"example-idempotencykey","adapterName":"STEDI"}}},"description":"`queueOnly` is fixed to true and defaults to true. `adapterName` defaults to `STEDI` as local metadata. `idempotencyKey` may be stored as `stediCorrelationId` when supplied but is not proof of a live Stedi submission."},"responses":{"202":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/claims/{claimId}/status":{"get":{"operationId":"checkHomeHealthClaimStatus","summary":"Check home-health claim status","description":"Returns local claim status information for an organization-scoped home-health claim.\n\n### When to use\nUse this after queueing a home-health claim submission or during reconciliation when you need QuickRCM's latest local status marker.\n\n### Before calling\nAuthenticate with `specialty-billing:read` or `specialty-billing:write`. Use a claim id from the same organization.\n\n### Request guidance\nPass `claimId` in the path. No query parameters or request body are currently declared.\n\n### Request notes\n- No clearinghouse status inquiry is performed inline.\n- Use this endpoint for local workflow status, not payer proof.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: LOCAL_STATUS_ONLY`, `claimId`, the local claim status, and the latest local `ClaimStatusCheck` when available. It does not poll a clearinghouse inline.\n\n### Response notes\n- `LOCAL_STATUS_ONLY` distinguishes local state from external claim status.\n- `latestStatusCheck` may be null if no local check exists.\n- The returned claim status is the local Claim status field.\n\n### Errors and retries\nA 404 means the claim was not found in the authenticated organization. Retry rate-limit or transient server failures with backoff.\n\n### Error notes\n- 404 hides wrong-tenant claim identifiers.\n- Avoid tight polling on queued claims.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"Claim identifier in the path."}],"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/referrals":{"post":{"operationId":"createHomeHealthReferral","summary":"Create home-health referral","description":"Creates a local home-health referral intake record for the authenticated organization.\n\n### When to use\nUse this to capture referral intake metadata before triage, acceptance, decline, or conversion to an episode.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Resolve optional `patientId` and `facilityId` inside the same organization if you include them.\n\n### Request guidance\nAll body fields are optional. `documentFileIds` defaults to an empty array. `receivedAt` defaults to the current time when omitted. Keep `metadata` and source fields sanitized.\n\n### Request notes\n- Optional patient/facility references are organization checked.\n- Document IDs are stored as references; do not include S3 keys or signed URLs.\n- Avoid PHI-heavy free text in referral source or metadata fields.\n\n### Response semantics\nHTTP 201 returns `externalRiskMode: SAFE_WRITE_DB_ONLY` and the created referral with local status `NEW`. No episode, claim, payer request, or document fetch is created by this endpoint.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` means a local referral row was created.\n- The referral starts with local status `NEW`.\n- No downstream episode conversion happens automatically.\n\n### Errors and retries\nA 404 can mean the optional patient or facility reference does not belong to the authenticated organization. After timeouts, search local referrals before retrying.\n\n### Error notes\n- 400 can indicate invalid date or string lengths.\n- 404 can indicate wrong-tenant patient/facility references.\n- Avoid duplicate referral creation after uncertain writes.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":["string","null"],"minLength":1,"description":"Optional nullable QuickRCM patient identifier in the API-key organization."},"facilityId":{"type":["string","null"],"minLength":1,"description":"Optional nullable facility identifier in the API-key organization."},"referralSourceType":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"Optional local referral source category label."},"referralSourceName":{"type":["string","null"],"minLength":1,"maxLength":160,"description":"Optional local referral source name."},"receivedAt":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO referral receipt date/datetime; defaults to current time when omitted."},"priority":{"type":["string","null"],"minLength":1,"maxLength":40,"description":"Optional local referral priority label up to 40 characters, such as a workflow urgency code chosen by the organization."},"primaryDiagnosisCode":{"type":["string","null"],"minLength":1,"description":"Optional primary diagnosis code for referral intake; the API stores the normalized uppercase value."},"documentFileIds":{"type":"array","items":{"type":"string","minLength":1},"default":[],"description":"Optional File identifiers to associate with the referral."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional local JSON metadata. Do not include PHI, credentials, raw vendor payloads, S3 keys, signed URLs, or raw EDI."}}},"example":{"patientId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","referralSourceType":"example-referralsourcetype","referralSourceName":"Example home_health_referral","receivedAt":"2026-06-08T10:15:30Z","priority":"example-priority","primaryDiagnosisCode":"example-primarydiagnosiscode","documentFileIds":[]}}},"description":"All body fields are optional. `documentFileIds` defaults to an empty array. `receivedAt` defaults to the current time when omitted. Keep `metadata` and source fields sanitized."},"responses":{"201":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/referrals/{referralId}/status":{"put":{"operationId":"updateHomeHealthReferralStatus","summary":"Update home-health referral status","description":"Updates the local status and optional metadata for an organization-scoped home-health referral.\n\n### When to use\nUse this after referral triage or operational review to move a referral through intake states.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a referral id from the same organization.\n\n### Request guidance\n`status` is required and must be `NEW`, `TRIAGED`, `ACCEPTED`, `DECLINED`, or `CONVERTED`. `metadata` is optional sanitized local JSON.\n\n### Request notes\n- Use status values exactly as declared.\n- Keep metadata sanitized.\n- The status change is local workflow state only.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: SAFE_WRITE_DB_ONLY` and the updated referral. This does not create an episode even when status is `CONVERTED`.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` means local persistence only.\n- The response data contains the updated referral object.\n- No external notification or payer action is implied.\n\n### Errors and retries\nTreat 404 as missing or wrong-tenant referral. Re-read referral state before retrying after ambiguous timeouts.\n\n### Error notes\n- 400 can indicate invalid status.\n- 404 hides wrong-organization referral ids.\n- Retry only after checking current state when a prior update may have succeeded.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"referralId","in":"path","description":"HomeHealthReferral identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["NEW","TRIAGED","ACCEPTED","DECLINED","CONVERTED"],"description":"Required local referral status: NEW, TRIAGED, ACCEPTED, DECLINED, or CONVERTED."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional local JSON metadata for status context. Do not include PHI, credentials, payer portal content, raw vendor payloads, S3 keys, signed URLs, or raw EDI."}},"required":["status"]},"example":{"status":"NEW","metadata":{}}}},"description":"`status` is required and must be `NEW`, `TRIAGED`, `ACCEPTED`, `DECLINED`, or `CONVERTED`. `metadata` is optional sanitized local JSON."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/authorizations":{"post":{"operationId":"createHomeHealthAuthorization","summary":"Create home-health authorization","description":"Creates a local home-health prior authorization tracker after verifying the episode and optional payer config.\n\n### When to use\nUse this to track payer authorization numbers, approved visit/unit counts, date windows, and denial context for a home-health episode.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Resolve `episodeId` and optional `payerConfigId` inside the same organization.\n\n### Request guidance\n`episodeId` is required. `status` defaults to `PENDING`. Visit/unit counts must be nonnegative integers when supplied. Date fields must be ISO date/datetime strings or null.\n\n### Request notes\n- `disciplines` defaults to an empty array.\n- `authNumber` is stored locally when provided.\n- Do not include payer portal payloads or credentials in metadata.\n\n### Response semantics\nHTTP 201 returns `externalRiskMode: SAFE_WRITE_DB_ONLY` and the created authorization tracker. The endpoint does not submit or check an authorization request with a payer.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` means local tracker creation only.\n- No payer authorization submission occurs.\n- The response data contains the local authorization object.\n\n### Errors and retries\nA 404 can mean the episode or payer config does not belong to the organization. After ambiguous timeouts, search by episode/auth number before retrying.\n\n### Error notes\n- 400 can indicate invalid status, counts, dates, or string lengths.\n- 404 can indicate wrong-tenant episode or payer config.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"episodeId":{"type":"string","minLength":1,"description":"Required HomeHealthEpisode identifier in the API-key organization."},"payerConfigId":{"type":["string","null"],"minLength":1,"description":"Optional nullable payer configuration identifier in the API-key organization."},"status":{"type":"string","enum":["NOT_REQUIRED","PENDING","APPROVED","DENIED","EXPIRED"],"default":"PENDING","description":"Local authorization status: NOT_REQUIRED, PENDING, APPROVED, DENIED, or EXPIRED; defaults to PENDING."},"authNumber":{"type":["string","null"],"minLength":1,"maxLength":120,"description":"Optional nullable payer authorization number stored locally."},"disciplines":{"type":"array","items":{"type":"string","minLength":1,"maxLength":20},"default":[],"description":"Optional discipline labels, each up to 20 characters."},"authorizedVisits":{"type":["integer","null"],"minimum":0,"description":"Optional nullable nonnegative authorized visit count."},"authorizedUnits":{"type":["integer","null"],"minimum":0,"description":"Optional nullable nonnegative authorized unit count."},"effectiveStartDate":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO date or datetime when the authorization begins."},"effectiveEndDate":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO date or datetime when the authorization ends."},"submittedAt":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO date or datetime when the authorization request was submitted."},"approvedAt":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO date or datetime when the authorization was approved."},"deniedAt":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO date or datetime when the authorization was denied."},"denialReason":{"type":["string","null"],"minLength":1,"maxLength":1000,"description":"Optional nullable local denial reason capped at 1000 characters."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional JSON object for caller-owned local workflow metadata. Do not place PHI, credentials, payer portal content, or raw vendor payloads here."}},"required":["episodeId"]},"example":{"episodeId":"00000000-0000-4000-8000-000000000001","payerConfigId":"00000000-0000-4000-8000-000000000001","status":"PENDING","authNumber":"example-authnumber","disciplines":[],"authorizedVisits":1,"authorizedUnits":1,"effectiveStartDate":"2026-06-08","effectiveEndDate":"2026-06-08"}}},"description":"`episodeId` is required. `status` defaults to `PENDING`. Visit/unit counts must be nonnegative integers when supplied. Date fields must be ISO date/datetime strings or null."},"responses":{"201":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/authorizations/{authorizationId}/usage":{"put":{"operationId":"updateHomeHealthAuthorizationUsage","summary":"Update home-health authorization usage","description":"Applies integer deltas to local used-visit and used-unit counters for a home-health authorization.\n\n### When to use\nUse this when visits or units have been consumed, or when an external workflow needs a signed correction to QuickRCM local authorization usage counters.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use an authorization id from the same organization.\n\n### Request guidance\n`usedVisitsDelta` and `usedUnitsDelta` default to 0. Send integer deltas; positive values increase counters and negative values are accepted by the current schema for correction-style decrements. `metadata` is optional sanitized local JSON.\n\n### Request notes\n- Delta updates use Prisma-style increment semantics; negative integers are accepted by the current schema and decrement the stored counter.\n- Send zero or omit a counter when you do not want it changed.\n- Do not include raw visit documentation or PHI in metadata.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: SAFE_WRITE_DB_ONLY` and the updated authorization. The endpoint updates local counters only and does not call a payer.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` means local counter persistence only.\n- The API increments `usedVisits` and `usedUnits`.\n- No payer balance check is performed.\n\n### Errors and retries\nA 404 means the authorization was not found in the authenticated organization. Re-read counter values after uncertain success before retrying a delta update.\n\n### Error notes\n- 404 hides wrong-tenant authorization ids.\n- Avoid blind retries because deltas can be applied more than once.\n- Use current authorization state to reconcile after timeouts.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"authorizationId","in":"path","description":"HomeHealthPriorAuthorization identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"usedVisitsDelta":{"type":["integer","null"],"default":0,"description":"Integer visit usage delta; defaults to 0. Positive values increase usage, and negative values are accepted by the current schema for corrections."},"usedUnitsDelta":{"type":["integer","null"],"default":0,"description":"Integer unit usage delta; defaults to 0. Positive values increase usage, and negative values are accepted by the current schema for corrections."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional local JSON metadata for usage context. Do not include PHI, visit transcripts, credentials, raw payer content, S3 keys, signed URLs, or raw EDI."}}},"example":{"usedVisitsDelta":0,"usedUnitsDelta":0,"metadata":{}}}},"description":"`usedVisitsDelta` and `usedUnitsDelta` default to 0. Send integer deltas; positive values increase counters and negative values are accepted by the current schema for correction-style decrements. `metadata` is optional sanitized local JSON."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/oasis/{assessmentId}/submit":{"post":{"operationId":"submitHomeHealthOasis","summary":"Queue home-health OASIS submission","description":"Marks a local home-health OASIS assessment as submitted/queued without calling EHR or CMS systems inline.\n\n### When to use\nUse this when an external workflow needs QuickRCM to reflect queued OASIS submission state for an existing assessment.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use an assessment id from the same organization.\n\n### Request guidance\n`queueOnly` is fixed to true and defaults to true. Optional `responsePayload` is stored as local readiness/response metadata; keep it sanitized and do not include raw CMS, EHR, or payer payloads.\n\n### Request notes\n- `queueOnly` must remain true.\n- `responsePayload` is local metadata, not a raw vendor payload channel.\n- No file upload is declared.\n\n### Response semantics\nHTTP 202 returns `externalRiskMode: QUEUED_ONLY`, the updated assessment, and side effects indicating no EHR or CMS call. The API sets local status to `SUBMITTED` and `submittedAt`.\n\n### Response notes\n- `QUEUED_ONLY` means local queued/submitted state.\n- `sideEffects.callsEhr` is false.\n- `sideEffects.callsCms` is false.\n\n### Errors and retries\nA 404 means the assessment was not found in the organization. After timeouts, read the assessment before retrying.\n\n### Error notes\n- 400 can indicate invalid body shape.\n- 404 can indicate wrong-tenant assessment id.\n- Avoid repeated submission markers after uncertain success.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"assessmentId","in":"path","description":"HomeHealthOasisAssessment identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; must be true for public submission requests."},"responsePayload":{"type":"object","additionalProperties":{},"description":"Optional local JSON readiness/response metadata; do not store raw CMS, EHR, payer, or clearinghouse payloads, PHI, credentials, S3 keys, signed URLs, or raw EDI."}}},"example":{"queueOnly":true,"responsePayload":{}}}},"description":"`queueOnly` is fixed to true and defaults to true. Optional `responsePayload` is stored as local readiness/response metadata; keep it sanitized and do not include raw CMS, EHR, or payer payloads."},"responses":{"202":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/claims/{claimId}/adrs":{"post":{"operationId":"createHomeHealthAdr","summary":"Validate home-health ADR creation","description":"Validates a home-health ADR request for a local claim without creating cross-module ADR side effects.\n\n### When to use\nUse this to confirm ADR request inputs are acceptable before a separate ADR workflow creates documents, cases, or payer submissions.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a claim id from the same organization.\n\n### Request guidance\n`requestedDocTypes` and `deadline` are required. `requestedDocTypes` must contain 1 to 50 strings. `validateOnly` is fixed to true and defaults to true. Optional requester/tracking fields are local preview context only.\n\n### Request notes\n- `validateOnly` must remain true.\n- Do not include raw payer request letters or PHI-rich text in requester fields.\n- This endpoint does not assemble documents.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: VALIDATION_ONLY`, status `validated`, claim id, requested document types, deadline, and side effects showing no ADR creation, document assembly, or payer submission.\n\n### Response notes\n- `sideEffects.createsAdr` is false.\n- `sideEffects.assemblesDocuments` is false.\n- `sideEffects.submitsPayer` is false.\n\n### Errors and retries\nA 404 means the claim was not found in the organization. Correct invalid document type arrays or dates before retrying.\n\n### Error notes\n- 400 can indicate empty `requestedDocTypes` or too many entries.\n- 404 can indicate wrong-tenant claim id.\n- Use the ADR module APIs for actual ADR lifecycle actions when documented.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"Claim identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requestedDocTypes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":50,"description":"Required array of 1 to 50 requested document type labels."},"deadline":{"type":"string","minLength":1,"description":"Required ISO ADR deadline date/datetime."},"receivedDate":{"type":"string","minLength":1,"description":"Optional ISO received date/datetime."},"requestorName":{"type":"string","minLength":1,"maxLength":160,"description":"Optional name or label of the party requesting the Additional Documentation Request, capped at 160 characters."},"requestorEntity":{"type":"string","minLength":1,"maxLength":160,"description":"Optional organization or payer-side entity label associated with the Additional Documentation Request, capped at 160 characters."},"trackingNumber":{"type":"string","minLength":1,"maxLength":120,"description":"Optional local payer/request tracking number."},"assignedTo":{"type":"string","minLength":1,"maxLength":128,"description":"Optional local assignee identifier or label."},"validateOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; validates and previews the ADR request without creating ADR records, assembling documents, or submitting to a payer."}},"required":["requestedDocTypes","deadline"]},"example":{"requestedDocTypes":["example-requesteddoctypes"],"deadline":"example-deadline","receivedDate":"2026-06-08","requestorName":"Example home_health_adr","requestorEntity":"example-requestorentity","trackingNumber":"example-trackingnumber","assignedTo":"example-assignedto","validateOnly":true}}},"description":"`requestedDocTypes` and `deadline` are required. `requestedDocTypes` must contain 1 to 50 strings. `validateOnly` is fixed to true and defaults to true. Optional requester/tracking fields are local preview context only."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/home-health/denials/{denialCaseId}/appeals":{"post":{"operationId":"createHomeHealthAppeal","summary":"Validate home-health appeal creation","description":"Validates home-health appeal creation inputs for an organization-scoped denial case.\n\n### When to use\nUse this as a safe preflight before a separate appeal workflow creates letters, packets, or payer submissions.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a denial case id from the same organization.\n\n### Request guidance\n`validateOnly` is fixed to true and defaults to true. No appeal body details beyond the safety flag are currently declared.\n\n### Request notes\n- `validateOnly` must remain true.\n- No supporting document upload is declared.\n- Use dedicated Appeals APIs for actual appeal lifecycle actions when documented.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: VALIDATION_ONLY`, status `validated`, denial case id, and side effects showing no appeal creation, letter generation, or payer submission.\n\n### Response notes\n- `sideEffects.createsAppeal` is false.\n- `sideEffects.generatesLetter` is false.\n- `sideEffects.submitsPayer` is false.\n\n### Errors and retries\nA 404 means the denial case was not found in the authenticated organization. Correct invalid path ids rather than retrying unchanged.\n\n### Error notes\n- 404 hides wrong-organization denial cases.\n- 400 can indicate invalid body shape.\n- Retry only transient failures.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"denialCaseId","in":"path","description":"DenialCase identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; validates and previews only."}}},"example":{"validateOnly":true}}},"description":"`validateOnly` is fixed to true and defaults to true. No appeal body details beyond the safety flag are currently declared."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/elections":{"post":{"operationId":"createHospiceElection","summary":"Create hospice election","description":"Creates a local hospice election and initial benefit periods for the authenticated organization.\n\n### When to use\nUse this when hospice billing workflow state must be initialized before notices, census activity, benefit-period claim previews, or hospice claims.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Resolve required patient and facility identifiers, and optional payer, insurance, attending provider, and hospice physician references inside the same organization.\n\n### Request guidance\n`patientId`, `facilityId`, `electionStartDate`, and `terminalDiagnosisCode` are required. `relatedDiagnosisCodes` defaults to an empty array. Diagnosis codes are uppercased. Optional date fields must be ISO date/datetime strings or null.\n\n### Request notes\n- The election starts as local status `ACTIVE` with local RCM state `ELECTION_SIGNED` in the public API.\n- Optional patient insurance is checked against the same patient and organization.\n- No hospice notice or claim is submitted by this endpoint.\n\n### Response semantics\nHTTP 201 returns `externalRiskMode: SAFE_WRITE_DB_ONLY`, the created election, and summarized initial benefit periods. The API creates local FIRST_90, SECOND_90, and SUBSEQUENT_60 period records.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` means local database records were written.\n- Benefit periods are summarized, not full ledger entries.\n- No clearinghouse or EHR side effect occurs.\n\n### Errors and retries\nA 404 can mean a linked patient, facility, payer config, provider, or patient-insurance record does not resolve in the organization. After uncertain success, inspect local elections before retrying.\n\n### Error notes\n- 400 can indicate invalid election dates or missing required fields.\n- 404 can indicate wrong-tenant linked records.\n- Avoid duplicate elections after ambiguous timeouts.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"patientId":{"type":"string","minLength":1,"description":"Required QuickRCM patient identifier in the API-key organization."},"facilityId":{"type":"string","minLength":1,"description":"Required facility identifier in the API-key organization."},"payerConfigId":{"type":"string","minLength":1,"description":"Optional payer configuration identifier in the API-key organization."},"patientInsuranceId":{"type":"string","minLength":1,"description":"Optional patient insurance identifier for the same patient and API-key organization."},"electionStartDate":{"type":"string","minLength":1,"description":"Required ISO hospice election start date/datetime."},"electionSignedAt":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO signature date/datetime."},"terminalDiagnosisCode":{"type":"string","minLength":1,"description":"Required terminal diagnosis code; stored uppercase."},"relatedDiagnosisCodes":{"type":"array","items":{"type":"string","minLength":1},"default":[],"description":"Optional related diagnosis code array; defaults to empty and is uppercased."},"attendingProviderId":{"type":["string","null"],"minLength":1,"description":"Optional nullable same-organization attending provider identifier."},"hospicePhysicianProviderId":{"type":["string","null"],"minLength":1,"description":"Optional nullable same-organization hospice physician provider identifier."}},"required":["patientId","facilityId","electionStartDate","terminalDiagnosisCode"]},"example":{"patientId":"00000000-0000-4000-8000-000000000001","facilityId":"00000000-0000-4000-8000-000000000001","electionStartDate":"2026-06-08","terminalDiagnosisCode":"example-terminaldiagnosiscode","payerConfigId":"00000000-0000-4000-8000-000000000001","patientInsuranceId":"00000000-0000-4000-8000-000000000001","electionSignedAt":"2026-06-08T10:15:30Z","relatedDiagnosisCodes":[],"attendingProviderId":"00000000-0000-4000-8000-000000000001","hospicePhysicianProviderId":"00000000-0000-4000-8000-000000000001"}}},"description":"`patientId`, `facilityId`, `electionStartDate`, and `terminalDiagnosisCode` are required. `relatedDiagnosisCodes` defaults to an empty array. Diagnosis codes are uppercased. Optional date fields must be ISO date/datetime strings or null."},"responses":{"201":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/elections/{electionId}":{"put":{"operationId":"updateHospiceElection","summary":"Update hospice election","description":"Updates safe local fields on an organization-scoped hospice election.\n\n### When to use\nUse this to maintain hospice election lifecycle status, signature/revocation/discharge dates, diagnosis codes, payer/insurance references, or provider references.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Use an election id from the same organization and resolve optional linked ids before sending them.\n\n### Request guidance\nThe schema accepts optional body fields. For current handler behavior, omitted or explicit null `electionSignedAt`, `revocationDate`, and `dischargeDate` values are written as null; send current date values when they must be preserved. `status` must be `DRAFT`, `ACTIVE`, `REVOKED`, `DISCHARGED`, or `EXPIRED`. Related diagnosis codes are uppercased when supplied.\n\n### Request notes\n- The route uses PUT because PATCH is not used for these Wasp public API routes.\n- If `patientInsuranceId` is supplied, it is checked against the election patient.\n- Provider and payer references are organization checked.\n- Current implementation treats omitted nullable date fields (`electionSignedAt`, `revocationDate`, `dischargeDate`) the same as null on this PUT route; preserve-by-omission should not be assumed for those dates.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: SAFE_WRITE_DB_ONLY` and the updated local election. This endpoint does not create benefit periods, notices, claims, or EHR updates.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` means local persistence only.\n- The response data contains the updated election object.\n- No notice or claim submission is implied.\n\n### Errors and retries\nA 404 can mean the election or linked reference was not found in the authenticated organization. Re-read current election state after ambiguous timeouts.\n\n### Error notes\n- 400 can indicate invalid enum or date values.\n- 404 can indicate missing or wrong-organization references.\n- Retry only after reconciling current state when a prior request may have succeeded.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"electionId","in":"path","description":"HospiceElection identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["DRAFT","ACTIVE","REVOKED","DISCHARGED","EXPIRED"],"description":"Optional local election status: DRAFT, ACTIVE, REVOKED, DISCHARGED, or EXPIRED."},"electionSignedAt":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO date or datetime when the hospice election was signed. Current handler behavior writes null when omitted or sent as null."},"revocationDate":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO revocation date/datetime. Current handler behavior writes null when omitted or sent as null."},"dischargeDate":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO discharge date/datetime. Current handler behavior writes null when omitted or sent as null."},"terminalDiagnosisCode":{"type":"string","minLength":1,"description":"Optional terminal diagnosis code; stored uppercase."},"relatedDiagnosisCodes":{"type":"array","items":{"type":"string","minLength":1},"description":"Optional replacement array of related hospice diagnosis codes; supplied values are stored uppercase."},"attendingProviderId":{"type":["string","null"],"minLength":1,"description":"Optional nullable Provider identifier for the attending provider in the API-key organization."},"hospicePhysicianProviderId":{"type":["string","null"],"minLength":1,"description":"Optional nullable Provider identifier for the hospice physician in the API-key organization."},"payerConfigId":{"type":["string","null"],"minLength":1,"description":"Optional nullable payer configuration identifier in the API-key organization."},"patientInsuranceId":{"type":["string","null"],"minLength":1,"description":"Optional nullable patient insurance identifier for the election patient and API-key organization."}}},"example":{"status":"DRAFT","electionSignedAt":"2026-06-08T10:15:30Z","revocationDate":"2026-06-08","dischargeDate":"2026-06-08","terminalDiagnosisCode":"example-terminaldiagnosiscode","relatedDiagnosisCodes":["example-relateddiagnosiscodes"],"attendingProviderId":"00000000-0000-4000-8000-000000000001","hospicePhysicianProviderId":"00000000-0000-4000-8000-000000000001"}}},"description":"The schema accepts optional body fields. For current handler behavior, omitted or explicit null `electionSignedAt`, `revocationDate`, and `dischargeDate` values are written as null; send current date values when they must be preserved. `status` must be `DRAFT`, `ACTIVE`, `REVOKED`, `DISCHARGED`, or `EXPIRED`. Related diagnosis codes are uppercased when supplied."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/elections/{electionId}/revocation":{"post":{"operationId":"recordHospiceRevocation","summary":"Record hospice revocation","description":"Records a local hospice revocation date and sets the local election status to `REVOKED`.\n\n### When to use\nUse this when hospice election revocation has been determined outside the public API and QuickRCM needs local lifecycle state updated.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use an election id from the same organization.\n\n### Request guidance\n`revocationDate` is required and must be an ISO date or datetime string.\n\n### Request notes\n- This is a lifecycle update, not a notice submission.\n- Do not include revocation documents or PHI-rich notes.\n- Use ISO date/datetime values.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: SAFE_WRITE_DB_ONLY` and the updated election. No notice, payer, EHR, or claim side effect is performed.\n\n### Response notes\n- The API sets status to `REVOKED`.\n- `SAFE_WRITE_DB_ONLY` means local update only.\n- The response contains the updated election.\n\n### Errors and retries\nA 404 means the election was not found in the organization. Re-read election state after timeouts before retrying.\n\n### Error notes\n- 400 can indicate invalid date.\n- 404 hides wrong-tenant election ids.\n- Avoid duplicate terminal-event updates after uncertain writes.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"electionId","in":"path","description":"HospiceElection identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"revocationDate":{"type":"string","minLength":1,"description":"Required ISO revocation date/datetime."}},"required":["revocationDate"]},"example":{"revocationDate":"2026-06-08"}}},"description":"`revocationDate` is required and must be an ISO date or datetime string."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/elections/{electionId}/discharge":{"post":{"operationId":"recordHospiceDischarge","summary":"Record hospice discharge","description":"Records a local hospice discharge date and sets the local election status to `DISCHARGED`.\n\n### When to use\nUse this when hospice discharge has been determined outside the public API and QuickRCM needs local lifecycle state updated.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use an election id from the same organization.\n\n### Request guidance\n`dischargeDate` is required and must be an ISO date or datetime string.\n\n### Request notes\n- This is a lifecycle update, not a claim or notice action.\n- Do not include discharge documents or PHI-rich notes.\n- Use ISO date/datetime values.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: SAFE_WRITE_DB_ONLY` and the updated election. No notice, payer, EHR, or claim side effect is performed.\n\n### Response notes\n- The API sets status to `DISCHARGED`.\n- `SAFE_WRITE_DB_ONLY` means local update only.\n- The response contains the updated election.\n\n### Errors and retries\nA 404 means the election was not found in the organization. Re-read election state after timeouts before retrying.\n\n### Error notes\n- 400 can indicate invalid date.\n- 404 hides wrong-tenant election ids.\n- Avoid duplicate terminal-event updates after uncertain writes.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"electionId","in":"path","description":"HospiceElection identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"dischargeDate":{"type":"string","minLength":1,"description":"Required ISO discharge date/datetime."}},"required":["dischargeDate"]},"example":{"dischargeDate":"2026-06-08"}}},"description":"`dischargeDate` is required and must be an ISO date or datetime string."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/census/imports/preview":{"post":{"operationId":"previewHospiceCensusImport","summary":"Preview hospice census import","description":"Validates hospice census import rows without writing ledger entries or syncing to an EHR.\n\n### When to use\nUse this as a safe preflight for census imports before any later commit or internal processing step.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Prepare 1 to 500 rows with at least the row fields your integration wants validated.\n\n### Request guidance\n`rows` is required and must include 1 to 500 JSON objects. `fileId` is optional preview context. `validateOnly` is fixed to true and defaults to true. Validation checks for a non-empty `electionId`; missing, null, or empty `serviceDate` values become row-level `SERVICE_DATE_MISSING` issues, while malformed non-empty date strings are request-level 400 errors.\n\n### Request notes\n- `validateOnly` must remain true.\n- Rows should contain synthetic examples in docs; avoid patient names, addresses, identifiers from real census files, raw EHR data, and other PHI.\n- Do not pass S3 keys or signed URLs in `fileId`; use QuickRCM file ids only when available.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: VALIDATION_ONLY`, row counts, per-row validation status/issues, and side effects showing no batch creation, ledger writes, or EHR sync.\n\n### Response notes\n- Rows missing `electionId` get `ELECTION_ID_MISSING`.\n- Rows with missing, null, or empty `serviceDate` get `SERVICE_DATE_MISSING`; malformed non-empty service dates currently return request-level 400 instead of a row issue.\n- `sideEffects.writesLedger` and `sideEffects.syncsEhr` are false.\n\n### Errors and retries\nCorrect invalid row arrays, malformed non-empty service dates, or oversized batches before retrying. This endpoint is safe to retry after correction because it is validation-only.\n\n### Error notes\n- 400 can indicate empty rows, more than 500 rows, or malformed non-empty row date values.\n- 401/403 require credential or scope correction.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string","minLength":1,"description":"Optional preview context returned with the validation response. Current handler evidence does not show this endpoint fetching or tenant-validating the File record; do not send S3 keys, signed URLs, or storage paths."},"rows":{"type":"array","items":{"type":"object","additionalProperties":{}},"minItems":1,"maxItems":500,"description":"Required array of 1 to 500 census row objects. Use synthetic rows in examples and avoid patient-identifying census details, raw EHR exports, credentials, or vendor payloads."},"validateOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; validates and previews only."}},"required":["rows"]},"example":{"rows":[{}],"fileId":"00000000-0000-4000-8000-000000000001","validateOnly":true}}},"description":"`rows` is required and must include 1 to 500 JSON objects. `fileId` is optional preview context. `validateOnly` is fixed to true and defaults to true. Validation checks for a non-empty `electionId`; missing, null, or empty `serviceDate` values become row-level `SERVICE_DATE_MISSING` issues, while malformed non-empty date strings are request-level 400 errors."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/census/imports/{batchId}/commit":{"post":{"operationId":"commitHospiceCensusImport","summary":"Queue hospice census import commit","description":"Queues a local hospice census import commit marker for an existing batch.\n\n### When to use\nUse this after a census import batch exists and should be marked for asynchronous/internal commit processing.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a census batch id from the same organization.\n\n### Request guidance\n`queueOnly` is fixed to true and defaults to true. No row payload is accepted on this commit endpoint.\n\n### Request notes\n- `queueOnly` must remain true.\n- No census rows are accepted here.\n- This is not proof that ledger entries were written.\n\n### Response semantics\nHTTP 202 returns `externalRiskMode: QUEUED_ONLY`, status `queued`, batch id, and side effects showing no inline ledger write or EHR sync. The API can update the local batch status to `QUEUED_COMMIT`.\n\n### Response notes\n- `QUEUED_ONLY` means local queued state.\n- `sideEffects.writesLedgerInline` is false.\n- `sideEffects.syncsEhrInline` is false.\n\n### Errors and retries\nA 404 means the batch was not found in the organization. After an ambiguous timeout, read the batch before retrying.\n\n### Error notes\n- 404 hides wrong-tenant batch ids.\n- Avoid repeated queue markers after uncertain success.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"batchId","in":"path","description":"HospiceCensusImportBatch identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; must be true."}}},"example":{"queueOnly":true}}},"description":"`queueOnly` is fixed to true and defaults to true. No row payload is accepted on this commit endpoint."},"responses":{"202":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/notices":{"post":{"operationId":"createHospiceNotice","summary":"Create hospice notice","description":"Creates a local hospice notice payload for an organization-scoped election without submitting it to a clearinghouse.\n\n### When to use\nUse this to prepare a local hospice NOE or NOTR notice before queueing submission.\n\n### Before calling\nAuthenticate with `specialty-billing:write`. Resolve `electionId` in the same organization and, if supplied, ensure `benefitPeriodId` belongs to that election.\n\n### Request guidance\n`electionId` and `noticeType` are required. `noticeType` must be `NOE` or `NOTR`. `effectiveDate` defaults to the election start date when omitted. Optional `payload` and `metadata` are stored locally and must use sanitized, synthetic values in examples.\n\n### Request notes\n- Only `NOE` and `NOTR` are declared notice types.\n- Benefit period linkage is checked against the supplied election.\n- Do not include raw EDI, payer portal output, or PHI-heavy content in `payload`.\n\n### Response semantics\nHTTP 201 returns `externalRiskMode: SAFE_WRITE_DB_ONLY` and the created local notice with status `READY`. No clearinghouse adapter is invoked.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` means local notice creation only.\n- The notice starts as `READY` in the public API.\n- Use submitHospiceNotice to create queued submission state.\n\n### Errors and retries\nA 404 can mean the election was not found or the benefit period does not belong to the election. After uncertain success, inspect local notices before retrying.\n\n### Error notes\n- 400 can indicate invalid notice type or dates.\n- 404 can indicate wrong-tenant election or mismatched benefit period.\n- Avoid duplicate notices after ambiguous timeouts.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"electionId":{"type":"string","minLength":1,"description":"Required HospiceElection identifier in the API-key organization."},"benefitPeriodId":{"type":["string","null"],"minLength":1,"description":"Optional nullable HospiceBenefitPeriod identifier that must belong to the supplied election."},"noticeType":{"type":"string","enum":["NOE","NOTR"],"description":"Required hospice notice type: NOE or NOTR."},"effectiveDate":{"type":"string","minLength":1,"description":"Optional ISO effective date/datetime; defaults to the election start date when omitted."},"dueDate":{"type":["string","null"],"minLength":1,"description":"Optional nullable ISO due date/datetime."},"payload":{"type":"object","additionalProperties":{},"description":"Optional local notice payload metadata; do not include raw EDI, payer portal output, raw EHR/CMS payloads, PHI, credentials, S3 keys, or signed URLs."},"metadata":{"type":"object","additionalProperties":{},"description":"Optional local JSON metadata; keep examples synthetic and omit PHI, credentials, raw vendor payloads, S3 keys, signed URLs, and raw EDI."}},"required":["electionId","noticeType"]},"example":{"electionId":"00000000-0000-4000-8000-000000000001","noticeType":"NOE","benefitPeriodId":"00000000-0000-4000-8000-000000000001","effectiveDate":"2026-06-08","dueDate":"2026-06-08","payload":{},"metadata":{}}}},"description":"`electionId` and `noticeType` are required. `noticeType` must be `NOE` or `NOTR`. `effectiveDate` defaults to the election start date when omitted. Optional `payload` and `metadata` are stored locally and must use sanitized, synthetic values in examples."},"responses":{"201":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/notices/{noticeId}/submit":{"post":{"operationId":"submitHospiceNotice","summary":"Queue hospice notice submission","description":"Queues a local hospice notice submission attempt and updates the notice to pending acknowledgement.\n\n### When to use\nUse this after creating a local hospice notice when an external workflow wants QuickRCM to track queued notice submission.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a notice id from the same organization.\n\n### Request guidance\n`queueOnly` is fixed to true and defaults to true. `adapterName` defaults to `STEDI`, but the endpoint records a local attempt instead of invoking a clearinghouse adapter inline. Optional `idempotencyKey` is stored as a local correlation id.\n\n### Request notes\n- `adapterName` is a local marker, not proof of live Stedi submission.\n- `queueOnly` must remain true.\n- `idempotencyKey` should not contain PHI or secrets.\n\n### Response semantics\nHTTP 202 returns `externalRiskMode: QUEUED_ONLY`, status `queued`, notice id, and the created submission attempt. The notice is updated to `PENDING_ACK` locally.\n\n### Response notes\n- `QUEUED_ONLY` means local queued state.\n- The public API records submission method `837I` and returns the created local submission attempt.\n- The attempt can include local payload metadata; docs should not show raw EDI.\n\n### Errors and retries\nA 404 means the notice was not found in the organization. After timeouts, read the notice and submission attempts before retrying.\n\n### Error notes\n- 400 can indicate invalid queue flag or body shape.\n- 404 hides wrong-tenant notice ids.\n- Avoid duplicate submission attempts after uncertain success.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"noticeId","in":"path","description":"HospiceNotice identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; must be true."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":160,"description":"Optional local correlation id, up to 160 characters."},"adapterName":{"type":"string","minLength":1,"maxLength":80,"default":"STEDI","description":"Optional local adapter label, defaulting to STEDI."}}},"example":{"queueOnly":true,"idempotencyKey":"example-idempotencykey","adapterName":"STEDI"}}},"description":"`queueOnly` is fixed to true and defaults to true. `adapterName` defaults to `STEDI`, but the endpoint records a local attempt instead of invoking a clearinghouse adapter inline. Optional `idempotencyKey` is stored as a local correlation id."},"responses":{"202":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/notices/{noticeId}/acknowledgement":{"post":{"operationId":"acknowledgeHospiceNotice","summary":"Acknowledge hospice notice","description":"Records a local hospice notice acknowledgement and updates local notice acknowledgement state.\n\n### When to use\nUse this when an external clearinghouse or payer acknowledgement has already been interpreted and QuickRCM needs local acknowledgement state recorded.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a notice id from the same organization.\n\n### Request guidance\n`status` and `acknowledgementDate` are required. `status` must be `ACCEPTED`, `REJECTED`, `PARTIAL`, or `INFORMATIONAL`. Optional payer control number, rejection code, and message are stored locally; do not include raw acknowledgement payloads.\n\n### Request notes\n- This endpoint records interpreted acknowledgement fields, not raw 999/277CA/clearinghouse payloads.\n- `payerControlNumber` and `rejectionCode` are optional local fields.\n- Keep `message` concise and sanitized.\n\n### Response semantics\nHTTP 201 returns `externalRiskMode: SAFE_WRITE_DB_ONLY` and the created acknowledgement. The API records an empty raw payload and can update the notice to ACCEPTED, REJECTED, or PENDING_ACK depending on acknowledgement status.\n\n### Response notes\n- `SAFE_WRITE_DB_ONLY` means local acknowledgement persistence only.\n- ACCEPTED maps the notice to accepted local state; REJECTED maps to rejected; other statuses leave it pending acknowledgement.\n- No payer or clearinghouse call is made.\n\n### Errors and retries\nA 404 means the notice was not found in the authenticated organization. After timeouts, read acknowledgement and notice state before retrying.\n\n### Error notes\n- 400 can indicate invalid status or date values.\n- 404 hides wrong-tenant notice ids.\n- Avoid duplicate acknowledgement rows after uncertain success.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"noticeId","in":"path","description":"HospiceNotice identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ACCEPTED","REJECTED","PARTIAL","INFORMATIONAL"],"description":"Required interpreted acknowledgement status: ACCEPTED, REJECTED, PARTIAL, or INFORMATIONAL."},"acknowledgementDate":{"type":"string","minLength":1,"description":"Required ISO acknowledgement date/datetime."},"payerControlNumber":{"type":"string","minLength":1,"maxLength":120,"description":"Optional payer control number stored locally."},"rejectionCode":{"type":"string","minLength":1,"maxLength":80,"description":"Optional local rejection code."},"message":{"type":"string","minLength":1,"maxLength":2000,"description":"Optional sanitized acknowledgement message, up to 2000 characters."}},"required":["status","acknowledgementDate"]},"example":{"status":"ACCEPTED","acknowledgementDate":"2026-06-08","payerControlNumber":"example-payercontrolnumber","rejectionCode":"example-rejectioncode","message":"Request failed"}}},"description":"`status` and `acknowledgementDate` are required. `status` must be `ACCEPTED`, `REJECTED`, `PARTIAL`, or `INFORMATIONAL`. Optional payer control number, rejection code, and message are stored locally; do not include raw acknowledgement payloads."},"responses":{"201":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/benefit-periods/{benefitPeriodId}/claim-draft":{"post":{"operationId":"draftHospiceClaim","summary":"Preview hospice claim draft","description":"Validates and previews hospice claim-draft readiness for a local benefit period.\n\n### When to use\nUse this before hospice claim submission workflows to confirm benefit-period availability and preview the linked or supplied claim id.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a benefit period from the same organization.\n\n### Request guidance\n`validateOnly` is fixed to true and defaults to true. `claimId` is optional and returned as preview context when supplied.\n\n### Request notes\n- `validateOnly` must remain true.\n- No raw hospice billing payload is accepted.\n- This endpoint is validation-only even though it is a POST.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: VALIDATION_ONLY`, status `validated`, benefit period id, preview claim id, and side effects showing no claim, EDI payload, or clearinghouse submission is created.\n\n### Response notes\n- `sideEffects.createsClaim` is false.\n- `sideEffects.createsEdiPayload` is false.\n- `sideEffects.submitsClearinghouse` is false.\n\n### Errors and retries\nA 404 means the benefit period was not found in the authenticated organization. Correct identifiers before retrying.\n\n### Error notes\n- 404 hides wrong-tenant benefit period ids.\n- Do not present this endpoint as hospice claim generation.\n- Retry transient errors only with backoff.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"benefitPeriodId","in":"path","description":"HospiceBenefitPeriod identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; validates and previews only."},"claimId":{"type":"string","minLength":1,"description":"Optional claim identifier to echo as preview context."}}},"example":{"validateOnly":true,"claimId":"00000000-0000-4000-8000-000000000001"}}},"description":"`validateOnly` is fixed to true and defaults to true. `claimId` is optional and returned as preview context when supplied."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/claims/{claimId}/submit":{"post":{"operationId":"submitHospiceClaim","summary":"Queue hospice claim submission","description":"Queues a local hospice institutional claim submission marker and writes a local claim status check.\n\n### When to use\nUse this when a hospice institutional claim already exists in QuickRCM and should be marked queued for downstream submission tracking.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a same-organization claim id.\n\n### Request guidance\n`queueOnly` is fixed to true and defaults to true. `adapterName` defaults to `STEDI` as local metadata. `idempotencyKey` may be stored as local correlation metadata but does not prove live Stedi submission.\n\n### Request notes\n- No raw 837I payload is accepted or returned.\n- `adapterName` is a local marker.\n- `idempotencyKey` should not contain PHI or secrets.\n\n### Response semantics\nHTTP 202 returns `externalRiskMode: QUEUED_ONLY`, status `queued`, `claimId`, and `adapterName`. The API can update the local claim to `QUEUED` and create a local queued `ClaimStatusCheck`.\n\n### Response notes\n- `QUEUED_ONLY` means local queue/status state was recorded.\n- This endpoint does not return payer acceptance or adjudication.\n- Use checkHospiceClaimStatus for local status markers.\n\n### Errors and retries\nA 404 means the claim was not found in the authenticated organization. After a timeout, check local claim status before retrying.\n\n### Error notes\n- 400 can indicate invalid queue flag or body shape.\n- 404 can indicate missing or wrong-tenant claim.\n- Retry 429 and transient 5xx with backoff.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"Claim identifier in the path; it must belong to the API-key organization."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"queueOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; must be true for public submission requests."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":160,"description":"Optional local correlation id, up to 160 characters."},"adapterName":{"type":"string","minLength":1,"maxLength":80,"default":"STEDI","description":"Optional local adapter label, defaulting to STEDI."}}},"example":{"queueOnly":true,"idempotencyKey":"example-idempotencykey","adapterName":"STEDI"}}},"description":"`queueOnly` is fixed to true and defaults to true. `adapterName` defaults to `STEDI` as local metadata. `idempotencyKey` may be stored as local correlation metadata but does not prove live Stedi submission."},"responses":{"202":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/claims/{claimId}/status":{"get":{"operationId":"checkHospiceClaimStatus","summary":"Check hospice claim status","description":"Returns local claim status information for an organization-scoped hospice claim.\n\n### When to use\nUse this after queueing a hospice claim submission or during reconciliation when you need QuickRCM's latest local status marker.\n\n### Before calling\nAuthenticate with `specialty-billing:read` or `specialty-billing:write`. Use a claim id from the same organization.\n\n### Request guidance\nPass `claimId` in the path. No query parameters or request body are currently declared.\n\n### Request notes\n- No clearinghouse status inquiry is performed inline.\n- Use this endpoint for local workflow status, not payer proof.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: LOCAL_STATUS_ONLY`, `claimId`, the local claim status, and the latest local `ClaimStatusCheck` when available. It does not poll a clearinghouse inline.\n\n### Response notes\n- `LOCAL_STATUS_ONLY` distinguishes local state from external claim status.\n- `latestStatusCheck` may be null if no local check exists.\n- The returned claim status is the local Claim status field.\n\n### Errors and retries\nA 404 means the claim was not found in the authenticated organization. Retry rate-limit or transient server failures with backoff.\n\n### Error notes\n- 404 hides wrong-tenant claim identifiers.\n- Avoid tight polling on queued claims.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"Claim identifier in the path."}],"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/claims/{claimId}/adrs":{"post":{"operationId":"createHospiceAdr","summary":"Validate hospice ADR creation","description":"Validates a hospice ADR request for a local claim without creating cross-module ADR side effects.\n\n### When to use\nUse this to confirm hospice ADR request inputs are acceptable before a separate ADR workflow creates documents, cases, or payer submissions.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a claim id from the same organization.\n\n### Request guidance\n`requestedDocTypes` and `deadline` are required. `requestedDocTypes` must contain 1 to 50 strings. `validateOnly` is fixed to true and defaults to true.\n\n### Request notes\n- `validateOnly` must remain true.\n- Do not include raw payer request letters or PHI-rich text.\n- This endpoint does not assemble documents.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: VALIDATION_ONLY`, status `validated`, claim id, requested document types, deadline, and side effects showing no ADR creation, document assembly, or payer submission.\n\n### Response notes\n- `sideEffects.createsAdr` is false.\n- `sideEffects.assemblesDocuments` is false.\n- `sideEffects.submitsPayer` is false.\n\n### Errors and retries\nA 404 means the claim was not found in the organization. Correct invalid document type arrays or dates before retrying.\n\n### Error notes\n- 400 can indicate empty `requestedDocTypes` or too many entries.\n- 404 can indicate wrong-tenant claim id.\n- Use the ADR module APIs for actual ADR lifecycle actions when documented.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"claimId","in":"path","description":"Claim identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"requestedDocTypes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":50,"description":"Required array of 1 to 50 requested document type labels."},"deadline":{"type":"string","minLength":1,"description":"Required ISO ADR deadline date/datetime."},"validateOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; validates and previews only."}},"required":["requestedDocTypes","deadline"]},"example":{"requestedDocTypes":["example-requesteddoctypes"],"deadline":"example-deadline","validateOnly":true}}},"description":"`requestedDocTypes` and `deadline` are required. `requestedDocTypes` must contain 1 to 50 strings. `validateOnly` is fixed to true and defaults to true."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/specialty-billing/hospice/denials/{denialCaseId}/appeals":{"post":{"operationId":"createHospiceAppeal","summary":"Validate hospice appeal creation","description":"Validates hospice appeal creation inputs for an organization-scoped denial case.\n\n### When to use\nUse this as a safe preflight before a separate appeal workflow creates letters, packets, or payer submissions.\n\n### Before calling\nAuthenticate with `specialty-billing:write` and use a denial case id from the same organization.\n\n### Request guidance\n`validateOnly` is fixed to true and defaults to true. No appeal body details beyond the safety flag are currently declared.\n\n### Request notes\n- `validateOnly` must remain true.\n- No supporting document upload is declared.\n- Use dedicated Appeals APIs for actual appeal lifecycle actions when documented.\n\n### Response semantics\nHTTP 200 returns `externalRiskMode: VALIDATION_ONLY`, status `validated`, denial case id, and side effects showing no appeal creation, letter generation, or payer submission.\n\n### Response notes\n- `sideEffects.createsAppeal` is false.\n- `sideEffects.generatesLetter` is false.\n- `sideEffects.submitsPayer` is false.\n\n### Errors and retries\nA 404 means the denial case was not found in the authenticated organization. Correct invalid path ids rather than retrying unchanged.\n\n### Error notes\n- 404 hides wrong-organization denial cases.\n- 400 can indicate invalid body shape.\n- Retry only transient failures.\n","tags":["Specialty Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"denialCaseId","in":"path","description":"DenialCase identifier in the path."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"validateOnly":{"type":"boolean","enum":[true],"default":true,"description":"Required safety flag; validates and previews only."}}},"example":{"validateOnly":true}}},"description":"`validateOnly` is fixed to true and defaults to true. No appeal body details beyond the safety flag are currently declared."},"responses":{"200":{"description":"Specialty billing workflow response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","additionalProperties":{}},"meta":{"type":"object","properties":{"organizationId":{"type":"string"},"externalRiskMode":{"type":"string","enum":["SAFE_WRITE_DB_ONLY","QUEUED_ONLY","SIMULATED_ONLY","VALIDATION_ONLY","LOCAL_STATUS_ONLY"]}},"required":["organizationId","externalRiskMode"]}},"required":["success","data","meta"]},"example":{"success":true,"data":{},"meta":{"organizationId":"00000000-0000-4000-8000-000000000001","externalRiskMode":"SAFE_WRITE_DB_ONLY"}}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"The requested organization does not match the authenticated caller.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"The requested specialty billing resource was not found in the authenticated organization.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"API key rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/support/tickets":{"get":{"operationId":"listSupportTickets","summary":"List support tickets","description":"Returns local Support ticket snapshots for the bearer-key organization and the synthetic public API actor selected by current public API authentication behavior.\n\n### When to use\nUse this endpoint to reconcile recently filed Support tickets or display the current actor's visible ticket history in an external support workflow.\n\n### Before calling\nAuthenticate with a tenant-scoped bearer API key. This read endpoint accepts `support:read` or `support:write`; the shared auth helper also accepts `support:*`, `public-api:*`, or `*` through wildcard matching.\n\n### Request guidance\nThe OpenAPI operation defines no request body, path parameters, or query parameters. Do not document pagination, search, status filters, `organizationId`, `userId`, or all-organization list behavior for this endpoint.\n\n### Request notes\n- No request body is accepted.\n- No path or query parameters are part of the documented public contract.\n- `organizationId` is derived from authentication context and should not be documented as a tenant selector.\n- Use returned opaque `id` values as `ticketId` path parameters for getSupportTicket.\n\n### Response semantics\nA 200 response returns `success: true` and `data.tickets`. Current operation behavior orders visible tickets by `createdAt` descending and returns at most 100 records. Each row is a local QuickRCM SupportTicket snapshot for the resolved actor and organization, not an external help desk record, all-organization queue, or SLA commitment.\n\n### Response notes\n- `data.tickets[]` contains only tickets visible to the synthetic public API actor in the authenticated organization.\n- The response does not represent all Support tickets in the organization.\n- `subject` and `description` are persisted caller-entered ticket text and can be sensitive if submitted incorrectly; clients should not echo them into logs, analytics, traces, or downstream tools without redaction.\n- Resolution fields can be null for open or unresolved tickets.\n- Comments, attachments, assignment data, SLA targets, notification delivery state, and admin-only queue fields are not returned.\n\n### Errors and retries\nTreat 401 as missing or invalid authentication, 403 as missing accepted Support scope or missing actor membership, 429 as API-key rate limiting, and 500 as a transient server-side failure. Back off on 429 and avoid tight polling loops.\n\n### Error notes\n- 400 is declared in the OpenAPI contract as a standard invalid request response, although the current list schema defines no accepted query fields.\n- 401 and 403 require credential, scope, or membership correction before retrying.\n- After a 500, retry cautiously and compare returned `id` values before assuming a ticket is missing.\n","tags":["Support"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Support tickets for the authenticated organization","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"tickets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"category":{"type":"string","enum":["STC_BUG","STC_FEATURE_REQUEST","STC_QUESTION","STC_BILLING","STC_INTEGRATION","STC_PERFORMANCE","STC_ACCOUNT","STC_OTHER"]},"priority":{"type":"string","enum":["STP_LOW","STP_MEDIUM","STP_HIGH","STP_CRITICAL"]},"status":{"type":"string","enum":["ST_OPEN","ST_IN_PROGRESS","ST_WAITING_ON_USER","ST_RESOLVED","ST_CLOSED"]},"subject":{"type":"string"},"description":{"type":"string"},"pageUrl":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolutionNotes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","category","priority","status","subject","description","pageUrl","userAgent","resolvedAt","resolutionNotes","createdAt","updatedAt"]}}},"required":["tickets"]}},"required":["success","data"]},"example":{"success":true,"data":{"tickets":[{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","category":"STC_BUG","priority":"STP_LOW","status":"ST_OPEN","subject":"example-subject","description":"Example support_ticket note","pageUrl":"https://example.quickintell.com/resource","userAgent":"example-useragent","resolvedAt":"2026-06-08T10:15:30Z","resolutionNotes":"Example support_ticket note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}},"post":{"operationId":"createSupportTicket","summary":"Create support ticket","description":"Creates a local SupportTicket record inside the organization selected by the bearer API key and owned by the synthetic public API actor selected by current authentication behavior.\n\n### When to use\nUse this endpoint when an external portal, integration, or operations tool needs to file a sanitized QuickRCM support issue, question, billing concern, account issue, performance issue, integration issue, feature request, or other support item.\n\n### Before calling\nAuthenticate with a tenant-scoped bearer API key that has `support:write`; wildcard scopes `support:*`, `public-api:*`, or `*` are also accepted by the shared auth helper. Prepare a valid category, concise sanitized subject, and sanitized details.\n\n### Request guidance\nSend `category`, `subject`, and `description`. Optionally send `priority`, `pageUrl`, and `userAgent`. Do not send `organizationId`, `userId`, `status`, `resolvedAt`, `resolutionNotes`, comments, attachments, screenshots, assignment fields, raw payloads, credentials, tokens, or PHI.\n\n### Request notes\n- `category` is required and must be one of the documented `STC_*` enum values.\n- `subject` is trimmed, required, and limited to 200 characters.\n- `description` is trimmed, required, and limited to 10000 characters.\n- `priority` is optional and defaults to `STP_MEDIUM` when omitted by current operation behavior.\n- `pageUrl` is optional, nullable, trimmed, limited to 2000 characters, and stored as caller-supplied context; the contract does not validate URL syntax.\n- `userAgent` is optional, nullable, trimmed, and limited to 500 characters.\n- Use opaque QuickRCM or caller-side correlation IDs in free text instead of patient identifiers, raw payer responses, EDI snippets, transcripts, storage keys, or vendor payloads.\n\n### Response semantics\nA 201 response returns the newly persisted local ticket snapshot. If `priority` is omitted, current operation behavior stores `STP_MEDIUM`; new tickets are stored as `ST_OPEN`. The response is not proof of notification email delivery, support acceptance, SLA start, or external help desk delivery.\n\n### Response notes\n- `data.id` is the opaque local ticket identifier to store for later get/list correlation.\n- `data.organizationId` is assigned from authentication context and is returned for correlation only.\n- `data.subject` and `data.description` echo persisted caller-entered text; do not write those values to logs, analytics, traces, or downstream ticketing systems unless redacted.\n- `data.status` is `ST_OPEN` for newly created tickets by current operation behavior.\n- `data.resolvedAt` and `data.resolutionNotes` are normally null for newly created tickets.\n- Support notification email is attempted after persistence in the underlying operation, but email failure is caught as non-fatal.\n\n### Errors and retries\nFix 400 validation failures before retrying. If a network timeout occurs after submission, call listSupportTickets before creating another ticket because this create operation does not expose an idempotency key and retrying can file a duplicate. Back off on 429.\n\n### Error notes\n- 400 means the request body failed required field, enum, min length, or max length validation.\n- 401 means the bearer API key is absent, malformed, invalid, inactive, expired, or otherwise not accepted.\n- 403 can mean the API key lacks an accepted Support write scope or the synthetic actor is not an active member of the selected organization.\n- 429 means the shared public API rate limit was exceeded for the API key.\n- 500 can occur if actor resolution fails because the organization has no active members or if another server error occurs.\n","tags":["Support"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","enum":["STC_BUG","STC_FEATURE_REQUEST","STC_QUESTION","STC_BILLING","STC_INTEGRATION","STC_PERFORMANCE","STC_ACCOUNT","STC_OTHER"],"description":"Required Support ticket category enum: `STC_BUG`, `STC_FEATURE_REQUEST`, `STC_QUESTION`, `STC_BILLING`, `STC_INTEGRATION`, `STC_PERFORMANCE`, `STC_ACCOUNT`, or `STC_OTHER`."},"priority":{"type":"string","enum":["STP_LOW","STP_MEDIUM","STP_HIGH","STP_CRITICAL"],"description":"Optional Support priority enum: `STP_LOW`, `STP_MEDIUM`, `STP_HIGH`, or `STP_CRITICAL`. Current operation behavior defaults an omitted value to `STP_MEDIUM`."},"subject":{"type":"string","minLength":1,"maxLength":200,"description":"Required short ticket title, trimmed to 1-200 characters. Keep it concise and sanitized; avoid PHI, secrets, raw EDI, transcripts, and raw external payloads."},"description":{"type":"string","minLength":1,"maxLength":10000,"description":"Required ticket details, trimmed to 1-10000 characters. Include reproduction steps and opaque correlation IDs; avoid patient identifiers, credentials, tokens, raw payer data, raw EHR/FHIR responses, transcripts, S3 keys, and raw EDI."},"pageUrl":{"type":["string","null"],"maxLength":2000,"description":"Optional nullable page context string for where the issue occurred, capped at 2000 characters. The public contract does not validate URL syntax; remove patient-identifying query strings, signed URLs, access tokens, and external portal session URLs."},"userAgent":{"type":["string","null"],"maxLength":500,"description":"Optional nullable browser or integration-client context, capped at 500 characters."}},"required":["category","subject","description"]},"example":{"category":"STC_BUG","subject":"example-subject","description":"Example support_ticket note","priority":"STP_LOW","pageUrl":"https://example.quickintell.com/resource","userAgent":"example-useragent"}}},"description":"Send `category`, `subject`, and `description`. Optionally send `priority`, `pageUrl`, and `userAgent`. Do not send `organizationId`, `userId`, `status`, `resolvedAt`, `resolutionNotes`, comments, attachments, screenshots, assignment fields, raw payloads, credentials, tokens, or PHI."},"responses":{"201":{"description":"Support ticket created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"category":{"type":"string","enum":["STC_BUG","STC_FEATURE_REQUEST","STC_QUESTION","STC_BILLING","STC_INTEGRATION","STC_PERFORMANCE","STC_ACCOUNT","STC_OTHER"]},"priority":{"type":"string","enum":["STP_LOW","STP_MEDIUM","STP_HIGH","STP_CRITICAL"]},"status":{"type":"string","enum":["ST_OPEN","ST_IN_PROGRESS","ST_WAITING_ON_USER","ST_RESOLVED","ST_CLOSED"]},"subject":{"type":"string"},"description":{"type":"string"},"pageUrl":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolutionNotes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","category","priority","status","subject","description","pageUrl","userAgent","resolvedAt","resolutionNotes","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","category":"STC_BUG","priority":"STP_LOW","status":"ST_OPEN","subject":"example-subject","description":"Example support_ticket note","pageUrl":"https://example.quickintell.com/resource","userAgent":"example-useragent","resolvedAt":"2026-06-08T10:15:30Z","resolutionNotes":"Example support_ticket note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}},"/api/v1/support/tickets/{ticketId}":{"get":{"operationId":"getSupportTicket","summary":"Get support ticket","description":"Returns one local SupportTicket snapshot when the path `ticketId` belongs to both the bearer-key organization and the synthetic public API actor selected by current authentication behavior.\n\n### When to use\nUse this endpoint after createSupportTicket or listSupportTickets returns an opaque ticket identifier and the integration needs the latest visible local ticket state.\n\n### Before calling\nAuthenticate with a tenant-scoped bearer API key. This read endpoint accepts `support:read` or `support:write`; wildcard scopes `support:*`, `public-api:*`, or `*` are also accepted by the shared auth helper. Use only ticket IDs returned from the same tenant and actor context.\n\n### Request guidance\nPass the `ticketId` path parameter only. Do not include a request body, query filters, tenant selectors, comments, attachments, status updates, assignment fields, or resolution fields.\n\n### Request notes\n- `ticketId` is required and must be a non-empty string.\n- Treat `ticketId` as opaque; do not infer UUID, prefix, sequence, or human ticket-number semantics.\n- Do not guess or enumerate ticket IDs.\n- Use a `ticketId` from a trusted Support create or list response from the same authenticated context.\n\n### Response semantics\nA 200 response returns the visible local ticket snapshot. A 404 means no ticket with that identifier is visible to the synthetic public API actor in the authenticated organization, or the ticket does not exist.\n\n### Response notes\n- The response ticket object has the same public fields returned by createSupportTicket.\n- `subject` and `description` are persisted caller-entered ticket text and can be sensitive; clients should not echo them into logs, analytics, traces, or downstream tools without redaction.\n- Resolution fields can be null for open or unresolved tickets.\n- The operation does not return comments, attachments, assignment, SLA data, notification delivery state, or admin-only queue metadata.\n\n### Errors and retries\nTreat 404 as missing, wrong-organization, or wrong-actor visibility unless a trusted same-context create/list response proves the ticket should exist. Retry 5xx cautiously and back off on 429.\n\n### Error notes\n- 400 means the path parameter failed validation.\n- 401 and 403 require credential, scope, or membership correction before retrying.\n- 404 can represent a missing ticket, wrong organization, or wrong public API actor visibility.\n- 429 indicates the API-key rate limit was exceeded.\n","tags":["Support"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"ticketId","in":"path","description":"Required opaque local Support ticket identifier from a trusted createSupportTicket or listSupportTickets response. It must be visible to the same authenticated organization and synthetic actor."}],"responses":{"200":{"description":"Support ticket","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"category":{"type":"string","enum":["STC_BUG","STC_FEATURE_REQUEST","STC_QUESTION","STC_BILLING","STC_INTEGRATION","STC_PERFORMANCE","STC_ACCOUNT","STC_OTHER"]},"priority":{"type":"string","enum":["STP_LOW","STP_MEDIUM","STP_HIGH","STP_CRITICAL"]},"status":{"type":"string","enum":["ST_OPEN","ST_IN_PROGRESS","ST_WAITING_ON_USER","ST_RESOLVED","ST_CLOSED"]},"subject":{"type":"string"},"description":{"type":"string"},"pageUrl":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolutionNotes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","category","priority","status","subject","description","pageUrl","userAgent","resolvedAt","resolutionNotes","createdAt","updatedAt"]}},"required":["success","data"]},"example":{"success":true,"data":{"id":"00000000-0000-4000-8000-000000000001","organizationId":"00000000-0000-4000-8000-000000000001","category":"STC_BUG","priority":"STP_LOW","status":"ST_OPEN","subject":"example-subject","description":"Example support_ticket note","pageUrl":"https://example.quickintell.com/resource","userAgent":"example-useragent","resolvedAt":"2026-06-08T10:15:30Z","resolutionNotes":"Example support_ticket note","createdAt":"2026-06-08T10:15:30Z","updatedAt":"2026-06-08T10:15:30Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Request validation failed","statusCode":400}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Authentication required","statusCode":401}}}},"403":{"description":"Caller is not authorized for the requested organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Forbidden","statusCode":403}}}},"404":{"description":"Support ticket not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Resource not found","statusCode":404}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Rate limit exceeded","statusCode":429}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"statusCode":{"type":"integer"}},"required":["error","statusCode"]},"example":{"error":"Internal server error","statusCode":500}}}}}}}},"webhooks":{},"tags":[{"name":"ADR","description":"ADR public API.\n\nAdditional Documentation Request (ADR) APIs manage claim-linked documentation request intake and local response tracking for records owned by the organization selected by the bearer API key. Use these endpoints to list and retrieve ADR work items, create local claim-linked ADR records, mark responses as submitted, preview document assembly gaps, register document-reference metadata, and record approved or denied outcomes.\n\nThe public ADR surface is intentionally metadata-oriented and conservative. Document assembly is simulation-only, document registration does not upload files or write storage objects, and response submission records local workflow state rather than proving payer receipt or adjudication. Treat requester details, tracking identifiers, document titles, outcome notes, and recovered amounts as sensitive healthcare workflow context.\n\nDo not put real protected health information (PHI), credentials, raw electronic data interchange (EDI), payer portal payloads, transcripts, S3 keys, or signed URLs in examples, logs, or retry keys."},{"name":"Agent Builder","description":"Agent Builder public API.\n\nAgent Builder public API endpoints let an authenticated tenant integration manage visual robotic process automation (RPA) agent definitions, schedules, safe execution wrapper records, credential discovery metadata, and reusable templates.\n\nThese endpoints are intentionally conservative: definition and schedule responses return safe metadata, template responses omit step bodies, credential responses omit stored usernames and secrets, and execution create/retry responses expose `dryRun`, `queueOnly`, and `browserAutomationStarted` safety controls instead of starting browser automation inline.\n\nUse these endpoints to configure and monitor organization-scoped automation around payer, electronic health record (EHR), clearinghouse, government, lab, pharmacy, registry, or custom portals. Do not send real protected health information (PHI), raw portal payloads, credentials, electronic data interchange (EDI) files, transcripts, or storage keys in examples or logs. Treat `inputParams`, `steps`, extraction schemas, schedule secrets, and execution output as sensitive workflow configuration.\n\nPublic read endpoints require Agent Builder read access; public write endpoints require the relevant Agent Builder automation write/admin permission, role-based access control (RBAC), and organization ownership checks."},{"name":"Appeals","description":"Appeals public API.\n\nAppeals APIs manage QuickRCM denial appeal records, supporting document workflows, peer-to-peer reviews, deadlines, reminders, analytics, and compliance tracking. All endpoints are scoped to the organization selected by the bearer API key; callers do not provide a public organization selector.\n\nUse these endpoints after a denial case, claim, supporting document, reminder, peer-to-peer review, compliance event, or compliance rule already exists in QuickRCM. Read endpoints accept `appeals:read` or `appeals:write`; write endpoints require `appeals:write`.\n\nThe public API exposes local workflow state and sanitized metadata. It intentionally avoids returning raw payer payloads, PHI-heavy activity metadata, S3 object keys, raw EDI, transcripts, or vendor credentials. Electronic portal appeal submission is validate-only through the public API and returns a simulated validation response rather than transmitting a payer payload."},{"name":"AR Management","description":"Accounts Receivable Management.\n\nAR Management APIs coordinate payer follow-up, work queues, correspondence, collection-stage movement, patient payment-plan tracking, financial-assistance review, and appeal tracking. These endpoints help teams organize revenue recovery work after claims, denials, patient balances, and payer responses already exist in QuickRCM."},{"name":"Billing","description":"Billing public API.\n\nBilling public API endpoints expose organization-scoped hospital billing encounters, coding review actions, physician query responses, batch imports, and Charge Description Master (CDM) maintenance. The surface is centered on `BillingEncounter` records and related review artifacts: code entries, POA indicators, DRG/E/M summaries, processing logs, physician queries, and CDM rate records.\n\nTenant scope is resolved from the bearer API key. Read endpoints accept `billing:read` or `billing:write`; create, update, queue, finalize, code-edit, physician-response, and CDM mutation endpoints require `billing:write`. Callers should pass QuickRCM identifiers returned by prior reads, imports, or adjacent setup workflows; do not send organization IDs as an authority signal, raw EDI, payer portal credentials, transcripts, S3 keys, signed URLs, full vendor payloads, or unnecessary clinical narrative.\n\nThe current Billing OpenAPI contract has detailed schemas for reads and queued workflows, but several mutation endpoints still use the generic mutation schema in generated OpenAPI while their handlers return concrete data. Client-facing docs should distinguish generated-schema guarantees from handler-observed runtime response fields, avoid promising unrelated Prisma columns as stable contract, and still recommend a follow-up read after queued workflows or state transitions when downstream processing is asynchronous."},{"name":"Claims","description":"Claims processing for professional, institutional, dental, attachment, claim-status, and predetermination workflows.\n\nClaims APIs manage QuickRCM claim records and safe local workflow tasks around X12 837 claim submission, X12 276/277 claim status checks, and X12 275-style supporting attachment metadata. Public endpoints are organization-scoped by the bearer API key and currently emphasize validation, local task creation, queueing, and metadata capture before any live clearinghouse execution is treated as publication-ready."},{"name":"Collections","description":"Collections public API.\n\nCollections APIs expose organization-scoped collection agency configuration, local bad debt placement tracking, recovery posting, placement dispute notes, safe debt validation notice simulation or queue evidence, and collections compliance rule/check workflows.\n\nThe bearer API key selects the organization. Public callers should not send an `organizationId` tenant selector. The public handlers enforce organization scope when looking up collection agencies, bad debt placements, and compliance rules.\n\nFor caller-supplied `patientId`, `patientAccountId`, and `claimIds` in placement creation, callers should use identifiers from the same authenticated organization; the public placement create endpoint stores those local references and does not document full referential validation for every supplied patient, account, or claim. For compliance checks, an optional `placementId` is used only for organization-scoped enrichment when found.\n\nThese endpoints manage QuickRCM local workflow state and audit evidence. They do not by themselves transmit debt to an external agency, send mail, email, or SMS, collect payment, post cash, update payer systems, or create legal compliance guarantees. Use synthetic examples only, and keep request notes free of Protected Health Information (PHI), credentials, tokens, raw Electronic Data Interchange (EDI), transcripts, S3 keys, payer portal credentials, payment card details, and vendor payloads.\n\nCompliance language should expand Telephone Consumer Protection Act (TCPA) and Fair Debt Collection Practices Act (FDCPA) on first use and avoid presenting local checks as legal advice."},{"name":"Contract Management","description":"Contract Management public API.\n\nContract Management APIs expose organization-scoped insurance contract inventory and local revenue-integrity workflow controls for contract list, detail, create, and update operations; what-if rate simulation drafts; fee schedule validation/import; underpayment detection; dispute-letter request recording; assignment; and resolution.\n\nThe bearer API key selects the organization. Public callers should not send `organizationId` as a tenant selector. Every referenced payer configuration, facility, contract, claim, underpayment case, assignee, fee schedule, rate schedule, simulation, activity, and audit row must resolve inside the authenticated organization.\n\nThese endpoints manage QuickRCM local state and audit evidence. They do not call payer systems, prove payer acceptance, upload or return contract files, generate or transmit live dispute letters, post cash, adjudicate claims, update Electronic Health Record (EHR) billing resources, or guarantee external recovery.\n\nUse synthetic examples and keep names, notes, rate-change context, dispute text, and import data free of real protected health information (PHI), credentials, tokens, raw Electronic Data Interchange (EDI), payer portal payloads, S3 keys, and vendor responses."},{"name":"Coordination of Benefits","description":"Coordination of Benefits public API.\n\nCoordination of Benefits (COB) APIs expose organization-scoped workflows for maintaining a patient's payer order, finding secondary-claim opportunities from primary Electronic Remittance Advice (ERA, commonly X12 835) data, generating local secondary claim records, queueing secondary-claim submission workflow, checking local secondary status, posting local secondary payment state, and voiding non-paid secondary claims.\n\nThe bearer API key selects the organization. Public callers should not send `organizationId` as a tenant selector. Medicare Secondary Payer (MSP) fields are local payer-order context unless an endpoint-specific response says otherwise. Read endpoints accept Coordination of Benefits read or write scope, while payer-order, detection, generation, submission, payment, and void endpoints require Coordination of Benefits write scope.\n\nReferenced patients, insurance identifiers, primary claims, remittances, secondary claims, payer identifiers, and generated records must resolve inside the authenticated organization.\n\nUse the secondary-claim lifecycle as local QuickRCM workflow state: generation creates or returns local `SC_GENERATED` records, submission accepts generated records and returns queue/submission metadata, status check reads submitted or acknowledged local status, payment posting can move eligible records to `SC_PAID` or `SC_DENIED`, and voiding marks eligible non-paid records `SC_VOID`. Crossover states (`SC_CROSSOVER_PENDING`, `SC_CROSSOVER_SENT`) are local lifecycle labels, not proof of payer completion by themselves.\n\nThese endpoints coordinate QuickRCM local workflow state. They do not return raw X12 837P professional claim Electronic Data Interchange (EDI), raw X12 835 ERA, raw X12 276/277 claim-status EDI, payer portal, Amazon S3 object-storage, or Electronic Health Record (EHR) payloads; they do not prove payer acceptance, final adjudication, EHR writeback, patient accounts receivable balance transfer, cash posting, or external reversal by themselves.\n\nUse synthetic examples and keep notes/reasons free of unnecessary Protected Health Information (PHI), raw EDI, credentials, tokens, payer portal data, transcripts, and vendor payloads."},{"name":"Credentialing","description":"Credentialing public API.\n\nCredentialing APIs expose organization-scoped credentialing session visibility and local workflow controls for provider credentialing packets. The public surface covers session creation and updates, provider profile fields, non-secret CAQH metadata, education, work history, licenses, professional references, liability insurance, signature file references, attestation acceptance, status updates, and safe simulated document/application workflows.\n\nThe bearer API key selects the organization. Public request bodies should not be documented as tenant selectors, and every session, document, File, payer configuration, assignee, or subresource lookup is scoped to that API-key organization. List and detail reads accept `credentialing:read` or `credentialing:write`; write operations require `credentialing:write`.\n\nSeveral endpoints deliberately avoid external or high-risk side effects. Document upload and document processing validate ownership and return `SIMULATED_ONLY`; they do not create S3-backed file records or invoke OCR/extraction. Application submit validates readiness and returns `VALIDATED_ONLY` or `SIMULATED_ONLY`; it does not submit to payer portals or move the local session status. CAQH public responses expose metadata and `hasPassword`, not password material.\n\nSession summaries expose `documentCount` from the local document relation count; session detail returns active document metadata filtered by `deletedAt: null` and ordered newest-first."},{"name":"Denial Management","description":"Denial Management public API.\n\nDenial Management APIs expose organization-scoped denial case read models, local denial workflow writes, remittance association, draft appeal creation, denial queue routing configuration, explicit case rerouting, and safe document-extraction validation.\n\nThe bearer API key selects the organization. Public requests should not send `organizationId` as a tenant selector. Read endpoints accept Denial Management read or write scope; mutation endpoints require Denial Management write scope. Referenced denial cases, queues, queue rules, remittances, draft appeals, users, and optional case links must resolve inside the authenticated organization.\n\nThese endpoints operate on QuickRCM local workflow state. They do not submit appeals to payers, run OCR or LLM extraction, upload files, parse ERA payloads, post payments, adjudicate claims, call clearinghouses, or guarantee denial recovery. Use synthetic examples and keep notes, rule metadata, letter HTML, filenames, and search/filter values free of real PHI, raw EDI, payer portal credentials, tokens, S3 keys, transcripts, and vendor payloads.\n\nIteration 2 adds complete queue-rule action and condition field semantics, common response-field glossary coverage, and PHI-safe synthetic request/response examples for all 10 Denial Management operations."},{"name":"EHR","description":"EHR public API.\n\nThe Electronic Health Record (EHR) public API exposes organization-scoped QuickRCM patient, appointment, patient-insurance, and appointment eligibility queueing endpoints. These endpoints are local QuickRCM API wrappers: patient, appointment, and insurance writes persist local database records; bulk patient import accepts inline JSON and stays database-only; and appointment eligibility creates a queued local eligibility-check record with `queueOnly: true` instead of contacting a payer, clearinghouse, or external EHR synchronously.\n\nUse these endpoints with a tenant-scoped bearer API key. The API key selects the organization; callers should not send `organizationId` as a tenant selector. Lookup/list endpoints require `ehr:read` or `ehr:write`, while create/update/queue endpoints require `ehr:write`. organizationId`. Public responses do not return address JSON, contact JSON, raw EHR payloads, raw payer payloads, raw EDI, credentials, transcripts, uploaded file contents, or other sensitive payloads.\n\nPatient names, dates of birth, Medical Record Numbers (MRNs), member identifiers, policy numbers, and contact details are Protected Health Information (PHI) or sensitive coverage data and should be logged only in redacted form.\n\nPatient matching behavior differs by endpoint. `findEhrPatientByDemographics` is a narrow lookup by exact trimmed first name, exact trimmed last name, and date-of-birth day. Patient create and bulk create use duplicate-detection helpers that can match same-organization demographics case-insensitively and also consider Medical Record Number (MRN) when supplied."},{"name":"EHR Integration","description":"EHR Integration public API.\n\nEHR Integration public APIs expose the tenant-scoped control plane for an organization's configured EHR connection: sanitized configuration summaries, local activation state, field and facility mappings, sync-log visibility, queue-only sync requests, dry-run validation, and conflict-resolution metadata. These endpoints are not raw Fast Healthcare Interoperability Resources (FHIR) proxy routes.\n\nPublic docs should distinguish returned local metadata from omitted sensitive identifiers. Local ids such as organizationId, config ids, mapping ids, syncLogId, integrationConfigId, entityConfigId, facilityId, and conflictId may be returned, and FACILITY mapping responses intentionally include externalFacilityId and externalSiteId.\n\nRaw vendor payload identifiers, sync-log internalId/externalId, conflict localData/remoteData values, raw request/response payloads, patient/source-record identifiers, credentials, endpoint URLs, transformConfig, webhook secrets, and patient demographics should not be documented as returned unless an endpoint schema explicitly does so.\n\nAuthentication is bearer API-key based. Read endpoints accept EHR Integration read access, while configuration mutations, mapping mutations, queue endpoints, validation endpoints, and conflict resolution require write-level EHR Integration access plus tenant authorization and role-based access control (RBAC). The API key selects the organization; public docs should not present organizationId as a caller-supplied tenant selector.\n\nSide-effect language should be precise. `testEhrConnection`, `validateEhrRecordSync`, and `validateEhrFullResync` are validation-only/dry-run routes. `activateEhrIntegrationConfig` and `deactivateEhrIntegrationConfig` are local database-only state transitions. `queueEhrManualSync` and `queueEpicBulkImport` return HTTP 202 queue acknowledgements and do not prove that an external EHR accepted or completed work.\n\nManual sync is publicly allowed only for PATIENT, APPOINTMENT, INSURANCE, and ENCOUNTER even though the shared entityType schema lists additional values for other EHR workflows."},{"name":"Eligibility","description":"Eligibility public API.\n\nEligibility APIs let integrations submit and retrieve tenant-scoped eligibility check summaries, then create, validate, inspect, and queue bulk eligibility batch wrappers. The bearer API key selects the organization for every operation; caller-supplied tenant selectors are not the public source of truth.\n\nPublic reference copy should make the safety boundary explicit. These endpoints return sanitized QuickRCM workflow summaries with local identifiers, status fields, and aggregate batch progress. They do not return patient demographics in responses, raw X12 271 Health Care Eligibility Benefit Response payloads, raw payer or clearinghouse payloads, raw Electronic Data Interchange (EDI), or proof of final payer payment.\n\nBatch endpoints work with comma-separated values (CSV) content or placeholder Amazon Simple Storage Service (Amazon S3) object metadata, while external worker and payer behavior is documented as local or queued state rather than inline Amazon Simple Queue Service (Amazon SQS) or payer execution."},{"name":"EOB to ERA","description":"EOB to ERA public API.\n\nExplanation of Benefits (EOB) to Electronic Remittance Advice (ERA) public APIs expose organization-scoped conversion tracking for EOB documents and safe local ERA classification workflow metadata. The bearer API key selects the organization; public requests should not include an `organizationId` tenant selector.\n\nThe current public surface is intentionally conservative. Read endpoints return sanitized conversion summaries and file-presence booleans, not file names, storage keys, signed URLs, raw EOB text, raw X12 835 Electronic Remittance Advice transaction payloads, or parser output. Write endpoints validate requests, create local records from existing organization-owned `File` rows, perform safe local status updates, or classify caller-supplied ERA summary fields.\n\nThese endpoints do not upload files, generate Amazon Simple Storage Service (S3) presigned URLs, enqueue Amazon Simple Queue Service (SQS) work, run optical character recognition (OCR) or large language model (LLM) extraction, parse raw payer payloads, submit claims, post payments, create denial records, or prove payer adjudication.\n\nUse synthetic examples and keep all notes, file names, and classification summaries free of real Protected Health Information (PHI), credentials, tokens, raw Electronic Data Interchange (EDI), transcripts, S3 keys, payer portal credentials, and vendor payloads."},{"name":"ERA","description":"ERA public API.\n\nERA public APIs expose organization-scoped Electronic Remittance Advice (ERA) retrieval and stored remittance access. The bearer API key selects the organization; public requests should not include `organizationId` or `orgId` tenant selectors.\n\nThe current public surface has two operations. `fetchEra` accepts a payer or trading-partner routing identifier plus a vendor transaction identifier, then attempts configured ERA vendor retrieval. When an automated vendor returns normalized details, QuickRCM stores or reuses a `Remittance` record and returns a direct sanitized ERA detail object. When no configured vendor is available or all vendor attempts fail, the endpoint creates a local high-priority manual task and returns HTTP 202 with an API acknowledgement.\n\n`getEra` reads a stored remittance by `eraId` only when that remittance belongs to the API-key organization and contains stored ERA detail data. address` can be null, address subfields can be null when an address object exists, claim status descriptions and service-line fields can be null, provider-adjustment reference IDs can be null, and arrays can be empty.\n\nThe public serializer keeps the response shape stable for incomplete normalized vendor data. Docs should state that required string fields may be empty strings, required numeric amount fields may be zero, nullable fields may be null, and arrays may be empty when the underlying normalized ERA does not contain that value.\n\nFor service-line amount fields, the public schema and serializer allow null when stored normalized service-line `chargeAmount` or `paidAmount` is absent or null; current Stedi-origin normalization maps missing or unparseable raw service-line amount strings to 0 before serialization. ERA detail responses intentionally omit patient names and member identifiers from claim rows.\n\nDo not describe these endpoints as payment posting, cash posting, denial creation, claim adjudication, payer acceptance, or direct raw X12 835 Electronic Data Interchange (EDI) remittance export. Route governance currently classifies ERA as compatibility-limited, so reference pages should document behavior with caveats and avoid happy-path guide language until route-class and release evidence change."},{"name":"Good Faith Estimates","description":"Good Faith Estimates public API.\n\nGood Faith Estimates APIs expose organization-scoped endpoints for local QuickRCM Good Faith Estimate creation, retrieval, editing, delivery-state recording, acknowledgment, voiding, PDF access, and local Independent Dispute Resolution case tracking.\n\nThe bearer API key selects the organization. Public callers should not send `organizationId` as a tenant selector. Read endpoints accept `gfe:read` or `gfe:write`; mutation endpoints require `gfe:write`. The patient, GFE, and IDR case identifiers used by these endpoints must resolve inside the authenticated organization. Optional `appointmentId` and `facilityId` values should be resolved by the caller before creation, but current implementation evidence visibly verifies patient ownership only before storing those optional identifiers.\n\nThese endpoints manage local workflow state for No Surprises Act support. They compute line totals, estimate totals, patient responsibility, and delivery-deadline metadata; record local delivery and acknowledgment state; create local IDR cases when a billed amount exceeds the estimate by at least 400; and expose PDF availability or access. They do not themselves transmit email, portal, fax, mail, or hand-delivery messages; submit an external IDR filing; adjudicate disputes; collect payments; update patient balances; or expose PDF storage keys.\n\nPDF access needs careful wording: S3-backed live responses return a presigned URL with a 300-second lifetime, while local PDF fallback can return a `data:application/pdf;base64,...` URL that still must be treated as sensitive PDF content and should not be logged or persisted.\n\nLifecycle summary: `GFE_DRAFT` and `GFE_GENERATED` can be updated, delivered, or voided; `GFE_DELIVERED` can be acknowledged or voided; `GFE_ACKNOWLEDGED` can initiate a qualifying local IDR case; `GFE_DISPUTED`, `GFE_EXPIRED`, and `GFE_VOID` are not editable, deliverable, or voidable through these public endpoints.\n\nIDR transitions are also constrained: initiated to offer submitted or withdrawn; offer submitted to counter received, provider-resolved, or withdrawn; counter received to arbitration, payer-resolved, split-resolved, or withdrawn; arbitration to provider-resolved, payer-resolved, or split-resolved."},{"name":"Insurance Discovery","description":"Insurance Discovery public API.\n\nInsurance Discovery APIs expose organization-scoped workflows for finding possible hidden coverage for self-pay or uninsured patients, reviewing local discovery search records, starting simulated batch discovery, retrying failed searches in simulated mode, and verifying or dismissing discovered coverage.\n\nThe bearer API key selects the organization. Public request bodies should not be documented as tenant selectors, and `organizationId` in responses is ownership/context metadata rather than a caller-controlled organization switch. Patient, search, and batch identifiers must resolve inside the authenticated organization.\n\nSearch inputs can include patient demographics and optional sensitive matching fields. Treat names, dates of birth, addresses, ZIP codes, Social Security number (SSN) last four digits, payer member IDs, discovered group IDs, and match details as Protected Health Information (PHI) or sensitive insurance data where applicable. Examples must stay synthetic, and public docs should discourage logging search terms, raw vendor payloads, Electronic Health Record (EHR) responses, credentials, tokens, storage keys, and payer portal data.\n\nThe public surface has mixed side-effect profiles. List and get endpoints read local QuickRCM Revenue Cycle Management (RCM) discovery records. `verifyDiscoveredCoverage` performs local database updates and is documented with `SAFE_WRITE_DB_ONLY` metadata. `startInsuranceDiscoveryBatch` and `retryInsuranceDiscoverySearch` require `simulateOnly: true` and return `SIMULATED_ONLY` metadata because those workflows can consume credits and call the simulated discovery vendor.\n\nRetry requests do not accept replacement demographics; current retry behavior reuses the failed search's stored first name, last name, date of birth, address, and ZIP code while not resubmitting stored SSN last-four. `runInsuranceDiscoverySearch` has no public `simulateOnly` flag; it can create a local PHI-bearing search record, consume discovery credits, and potentially transmit patient demographics to a discovery vendor, so document it with credit and privacy warnings.\n\nVerification should be described as a local QuickRCM coverage/account state update, not payer adjudication, eligibility verification, claim readiness, or EHR insurance write-back. Existing module docs state that direct EHR write-back is not wired from Insurance Discovery. Current public verification evidence supports creating a new local `PatientInsurance` record when discovered member data is available and storing that new identifier on the search; otherwise `patientInsuranceId` remains null.\n\nDownstream eligibility re-verification, claim use, payer configuration resolution, and optional EHR synchronization require separate workflows."},{"name":"Medical Coding","description":"Medical Coding public API.\n\nMedical Coding APIs expose organization-scoped CodingJob list/detail reads, local CodingJob creation, safe workflow-field updates, simulated extraction and rerun markers, coded-item review metadata, import-batch metadata, clarification answer capture, claims-handoff markers, outpatient upload and batch metadata, local outpatient check and draft state, Clinical Documentation Improvement (CDI) query lifecycle state, coding automation-rule configuration, and an unauthenticated static code-system directory.\n\nAuthenticated Medical Coding public API routes also use the module public API rate-limit action with a 60-request / 60-second window. If a caller is throttled, back off before retrying instead of polling tightly. The code-systems directory endpoint is declared without bearer authentication and returns static code-system metadata.\n\nFor authenticated Medical Coding operations, the bearer API key selects the organization. Public callers should not send `organizationId` as a tenant selector. Read endpoints accept Medical Coding read or write scopes; write endpoints require Medical Coding write scope.\n\nPath identifiers and linked records such as CodingJob, Appointment, ScribeJob, Claim, Patient, BillingEncounter, upload, CDI query, automation rule, and assignee user records must resolve inside the authenticated organization or the handler returns a not-found or authorization-style error.\n\nMost mutation endpoints manage QuickRCM local workflow state. They do not directly invoke a large language model (LLM), optical character recognition (OCR), electronic health record (EHR) write-back, payer or clearinghouse submission, claim creation, claim adjudication, electronic data interchange (EDI) exchange, or binary file upload unless a specific endpoint says otherwise. Safe markers such as `VALIDATED_ONLY`, `SIMULATED_ONLY`, `QUEUED_ONLY`, and `SAFE_WRITE_DB_ONLY` are local workflow markers, not external processing results.\n\nExamples must use synthetic identifiers and generic clinical/coding text only, with no protected health information (PHI), credentials, tokens, raw EDI, transcripts, S3 keys, payer portal credentials, signed URLs, or vendor payloads."},{"name":"OIG Exclusion","description":"OIG Exclusion public API.\n\nOIG Exclusion APIs expose organization-scoped exclusion-check records for Office of Inspector General (OIG) screening against List of Excluded Individuals/Entities (LEIE) and System for Award Management (SAM.gov) summary data. The bearer API key selects the authenticated organization; public request bodies should not be documented as tenant selectors.\n\nThe current public surface is intentionally conservative. organizationId`. The create endpoint accepts provider checks with a legal display name, `checkType: PROVIDER`, a 10-digit NPI, and a two-uppercase-letter state code; successful calls can return a recent existing check because the runtime deduplicates matching checks within the recent-check window. The bulk endpoint is dry-run only and returns `SIMULATED_ONLY` counts plus latest-run metadata without calling LEIE or SAM sources.\n\nThe resolution endpoint records a human false-positive or confirmed-excluded decision for resolvable local checks, and a confirmed-excluded decision can attempt internal organization-scoped follow-up. Do not describe public responses as raw federal-source exports, external EHR write-back, payer notification, or guaranteed claim holds."},{"name":"Patient AR","description":"Patient AR public API.\n\nPatient AR public APIs expose organization-scoped patient accounts receivable account lookup, local account maintenance, patient-responsibility charge posting, local payment application, payment-plan setup, statement draft creation, deposit-batch reconciliation, and collection-task activity logging.\n\nThe bearer API key selects the organization. Public callers should not send `organizationId` as a tenant selector; all account, patient, guarantor, facility, claim, charge, payment, plan, statement, deposit-batch, collection-task, activity, and assignee identifiers must resolve inside the authenticated organization. Read endpoints accept `patient-ar:read` or `patient-ar:write`; write endpoints require `patient-ar:write` plus Patient AR RBAC through the existing authorization helper.\n\nThis public surface is intentionally conservative around money movement and outbound contact. Cash, check, wire, and other non-card payment records can be created locally, then applied to local charges. Card, debit, and ACH payment requests must use validation, dry-run, or queue-only controls and do not call Stripe directly from the public handler. Refund and void endpoints validate or return queue-only acknowledgements; they do not settle refunds, void external payments, or mutate payment rows inline.\n\nStatement creation creates a local draft only, and collection endpoints record local task/activity state without sending email, SMS, letters, calls, legal notices, or agency placements.\n\nUse synthetic examples only. Account numbers, MRNs, patient or guarantor references, contact details, notes, payment references, check numbers, and collection activity can be PHI or sensitive financial data. Do not include raw EDI, payer portal credentials, tokens, S3 keys, vendor payloads, transcripts, or real payment method identifiers in public examples."},{"name":"Payer Enrollment","description":"Payer Enrollment public API.\n\nPayer Enrollment APIs expose organization-scoped provider enrollment profiles, payer-specific enrollment applications, local enrollment status tracking, follow-up notes, deficiencies, assignment, and safe validation workflows for credentialing sync and bulk import.\n\nThe bearer API key selects the organization. Public callers should not send `organizationId` as a tenant selector. Read endpoints require payer-enrollment read or write scope; mutation endpoints require payer-enrollment write scope. Referenced provider profiles, payer configurations, credentialing sessions, enrollment rows, deficiencies, applications, and assignees must resolve inside the authenticated organization.\n\nProvider identity fields include National Provider Identifier (NPI) values, Council for Affordable Quality Healthcare (CAQH) identifiers, Medicare identifiers, and other sensitive operational enrollment data.\n\nThis public surface is intentionally conservative. Application, provider-profile, follow-up, deficiency, assignment, enrollment, status, and clone endpoints update local QuickRCM records only. `submitPayerEnrollmentApplication`, `simulateSyncPayerEnrollmentProfileFromCredentialing`, and `bulkImportPayerEnrollments` are validation or dry-run surfaces that return `SIMULATED_ONLY` metadata and do not submit to payer portals, write provider data from credentialing, or import rows.\n\nWhen an application method names Electronic Data Interchange (EDI) or the Provider Enrollment, Chain, and Ownership System (PECOS), it is local workflow metadata unless a future private workflow provides separate evidence. Keep examples synthetic and keep notes free of Protected Health Information (PHI), portal credentials, OAuth tokens, raw EDI, raw payer payloads, S3 keys, and vendor responses.\n\nIteration 3 adds final materialization guidance for the reference pages: list responses are ordered by most recently updated application first, and simulated-only flows should show small synthetic examples that keep tenant selection implicit in the bearer API key."},{"name":"Payment Posting","description":"Payment Posting public API.\n\nPayment Posting public APIs expose organization-scoped remittance visibility, payment posting record detail, local remittance metadata updates, local matching controls, dry-run staging, safe posting validation, payer-ID refresh previews, and finalization validation for Electronic Remittance Advice (ERA) workflows.\n\nThe bearer API key selects the organization. Public callers should not send `organizationId` as a tenant selector. Read endpoints accept `payment-posting:read` or `payment-posting:write`; mutation and workflow endpoints require `payment-posting:write`.\n\nThis public surface is intentionally conservative. Read responses return sanitized local QuickRCM records and omit patient demographics, raw X12 835 Electronic Data Interchange (EDI), payer payloads, transcripts, credentials, and storage object details. Workflow endpoints that return `externalRisk: SIMULATED_ONLY` should be documented as validation, dry-run, or safe queue simulation responses.\n\nThey do not download Amazon Simple Storage Service (S3) objects, parse raw X12 835 payloads, create live queue work, post cash, mutate claim balances, deduct credits, or invoke Hash-based Message Authentication Code (HMAC) internal worker endpoints unless a future implementation changes the handler."},{"name":"Prevention","description":"Prevention public API.\n\nPrevention APIs expose organization-scoped public endpoints for claim pre-submission scrub queueing, denial-risk prediction queueing, prevention alert review, finding resolution, controlled auto-fix preview/application/revert, prevention rule lifecycle management, prediction feedback, provider education workflow, and learned payer-rule promotion.\n\nThe bearer API key selects the organization. Public callers should not send an `organizationId` selector. List and detail reads accept Prevention read or write scope; every mutation requires Prevention write scope. Referenced claims, claim lines, findings, predictions, rules, alerts, payer profiles, providers, education records, and auto-fix runs must belong to the authenticated organization.\n\norganizationId`; generated schema leaves `data` open-ended for several workflow endpoints, so endpoint examples should be treated as illustrative current handler behavior while the stable top-level envelope remains consistent. Alert list/detail and alert acknowledge endpoints return explicit alert objects.\n\nPublic scrub, batch scrub, prediction, and education generation endpoints are safe local workflows: `validateOnly` returns validation-only output, `dryRun` simulates without queueing, and `queueOnly` creates or reuses local work items where the handler supports queueing. These endpoints do not return payer acceptances, raw electronic data interchange (EDI), raw payer payloads, live large language model (LLM) output, or external dispatch evidence.\n\nUse only synthetic examples in public documentation. Alert and education text can contain operational context, so examples and guidance should avoid real protected health information (PHI), credentials, tokens, raw EDI, transcripts, S3 keys, payer portal credentials, vendor payloads, or patient demographic details.\n\nSafe-workflow request bodies may accept unknown passthrough properties at validation time, but those properties are not part of the public API contract. Do not use extra properties to send protected health information (PHI), raw claim payloads, raw electronic data interchange (EDI), vendor payloads, credentials, tokens, or payer portal details."},{"name":"Prior Authorization","description":"Prior Authorization public API.\n\nPrior Authorization APIs expose organization-scoped requirement checks, case creation and maintenance, draft saves, status transitions, renewals, local appeal tracking, bulk workflow queueing, bulk-upload batch status, and supporting-document upload setup for the tenant selected by the bearer API key.\n\nThe public reference should be explicit about side effects. Requirement checks return decision-support fields and do not create authorization cases. Case create/update/status/submit endpoints return sanitized QuickRCM prior authorization summaries, not payer approvals or denials. Renewal and appeal endpoints create or update local workflow records. Bulk authorization submissions and bulk-upload batches are queue-oriented public workflows.\n\nDocument submission endpoints are public validation surfaces that require `dryRun: true`; the OpenAPI descriptions state vendor submission is skipped.\n\nThe current draft-save OpenAPI request schema is an `allOf` body with the create-case request fields plus optional `priorAuthId`; documentation should not imply that draft save has an empty or undocumented body. If the final docs want partial-draft behavior, the public schema must be expanded or clarified first.\n\nThese endpoints can carry PHI or sensitive operational data in patient names, dates of birth, MRNs, member IDs, clinical indications, medical-necessity letters, appeal letters, document metadata, presigned upload URLs, and storage object keys. Public examples should be synthetic, and docs should tell callers not to log raw request bodies, upload URLs, S3 keys, payer portal credentials, raw EDI, transcripts, tokens, or vendor payloads.\n\nFor `createPriorAuth` and `savePriorAuthDraft`, the generated OpenAPI body shows `payerId` and `payerName` as individually optional, but the public contract enforces a cross-field rule: callers must provide at least one of them. The handler uses `payerName` when supplied, attempts to resolve known payer IDs, and can return 400 asking for an explicit `payerName` when a supplied `payerId` cannot be resolved."},{"name":"Reports","description":"Reports public API.\n\nReports public APIs expose a narrow, organization-scoped reporting surface: catalog discovery and one aggregate revenue-cycle summary. The bearer API key determines the authenticated organization; public callers should not send `organizationId` or `orgId` as tenant selectors.\n\nUse the catalog endpoint to discover public report definitions, supported filter identifiers, metric identifiers, and whether a report is `AVAILABLE` or `PLANNED`. Use the summary endpoint for the currently implemented `revenue-cycle-summary` aggregate metrics across claims and denial cases. The summary response is deliberately aggregate-only and omits patient-level rows, payer payloads, raw Electronic Data Interchange (EDI), raw Electronic Health Record (EHR) responses, and clinical-note text.\n\nExisting Reports module docs describe custom report builder, scheduled delivery, CSV/PDF exports, email delivery, and optional EHR archive behavior as placeholder or planned scope. Do not document those capabilities as implemented public API behavior unless a later OpenAPI operation explicitly exposes them."},{"name":"Revenue Integrity","description":"Revenue Integrity public API.\n\nRevenue Integrity APIs expose organization-scoped controls for dashboard metrics, underpayment recovery case lists, charge reconciliation, charge lag reporting, charge capture audits, operating room reconciliation, coding validation, contract rate validation, implant recovery tracking, underpayment appeal tracking, recovery recording, contract setup, and manual underpayment checks.\n\nThe bearer API key selects the organization. Public callers should not send an `organizationId` selector in these requests. Read endpoints accept `revenue-integrity:read` or `revenue-integrity:write`; write endpoints require `revenue-integrity:write`. Referenced claims, patients, facilities, billing encounters, payer configurations, contracts, charge reconciliation sessions, charge reconciliation items, and underpayment cases must belong to the authenticated organization.\n\nThis public surface is conservative. Some endpoints create or update local Revenue Integrity records. Other endpoints return `202 Accepted` for queued, validated, or dry-run local workflows. Those responses do not mean QuickRCM made a direct payer call, contacted a payer portal, submitted an appeal externally, changed an Electronic Health Record (EHR), posted cash, adjudicated a claim, or received a payer decision.\n\nUse synthetic examples and keep notes, descriptions, invoice identifiers, source record identifiers, and appeal references free of unnecessary Protected Health Information (PHI), raw Electronic Data Interchange (EDI), raw Electronic Remittance Advice (ERA), payer payloads, transcripts, credentials, tokens, S3 keys, and payer portal secrets.\n\nQueued workflow controls are consistent across the public Revenue Integrity endpoints that expose them: `validateOnly` validates ownership and request shape without creating a queued workflow; `dryRun` simulates the workflow when `validateOnly` is false; otherwise the API records a queued local workflow request. `queueOnly: false` by itself is not a request for direct payer, clearinghouse, or EHR execution."},{"name":"Risk Adjustment","description":"Risk Adjustment public API.\n\nRisk Adjustment APIs expose organization-scoped job workflow controls for patient-document risk adjustment processing and human review of Hierarchical Condition Category (HCC) code results. HCC outputs contribute to Risk Adjustment Factor (RAF) score fields, but the bearer API key selects the organization; public callers should not send an `organizationId` selector in these requests. All referenced jobs, patients, files, appointments, and HCC code review targets must belong to the authenticated organization.\n\nThe public surface is job-oriented and asynchronous. Create, bulk-create, and reprocess endpoints validate local QuickRCM references and either return validation output or queue local work; the OpenAPI descriptions state that public callers do not directly invoke optical character recognition (OCR) or artificial intelligence (AI) processing. Read endpoints return sanitized job summaries, HCC result summaries, and a limited patient-summary object.\n\nThey do not expose raw document chunks, raw evidence text, clinical note text, transcripts, raw electronic health record (EHR) payloads, raw payer payloads, signed storage URLs, review notes, protected health information (PHI) beyond the minimum documented identifiers, or raw electronic data interchange (EDI) payloads.\n\nThese endpoints do not submit diagnoses to the Centers for Medicare & Medicaid Services (CMS), send Risk Adjustment Processing System (RAPS) files, send Encounter Data Processing System (EDPS) files, adjudicate claims, update a payer portal, write back to an EHR, or certify final RAF/HCC accuracy. Use `reviewRiskAdjustmentHccCode` only to record a human decision for one HCC code. Treat `finalizedRafScore` and review fields as downstream workflow inputs only when the job state actually includes them and required review has completed.\n\nDiagnosis code fields use International Classification of Diseases, 10th Revision (ICD-10) code values where the response schema names them."},{"name":"Scribe","description":"Scribe public API.\n\nScribe public APIs expose organization-scoped clinical documentation job and template workflows for the AI Clinical Scribe module. The existing module docs describe Scribe as an ambient AI scribe that transcribes encounters and drafts SOAP notes; the public API surface narrows that product workflow to ten bearer-authenticated endpoints for jobs, file metadata attachment, asynchronous processing, attestation, and reusable templates.\n\nTenant context comes from the bearer API key. Public callers should not send `organizationId` or `orgId` tenant selectors. Read endpoints require Scribe read-capable credentials (`scribe:read` or `scribe:write`), while create, update, attach, attest, process, and template-write endpoints require `scribe:write` credentials.\n\nThe job lifecycle is asynchronous. `createScribeJob` creates a local job in `UPLOADING` status and immediately attempts to enqueue processing with the supplied audio reference. status=QUEUED`. Neither endpoint performs inline transcription, inline note generation, or synchronous clinical validation.\n\nThe public contract is intentionally conservative around clinical data and files. List responses return job summaries and `hasFinalNote` indicators, not raw transcripts, final notes, audio URLs, signed URLs, storage references, or vendor payloads. Detail and write responses can include `finalNote`, so examples and guidance must treat it as clinical documentation that can contain Protected Health Information (PHI).\n\nFile attachment records metadata for an already-uploaded organization-scoped audio file and returns sanitized file metadata; it does not upload file bytes, create presigned URLs, or echo storage references. Template endpoints manage reusable prompt configuration and should not be documented as patient-specific note content."},{"name":"SFTP EDI","description":"SFTP EDI public API.\n\nSFTP EDI documents Secure File Transfer Protocol (SFTP) handling for Electronic Data Interchange (EDI) file submission workflows. The public reference surface has one endpoint: `POST /api/v1/sftp/files/{fileId}/submit`.\n\nThe public endpoint is intentionally safe-mode only. It can validate that the authenticated organization owns an EDI file, or queue local QuickRCM work by marking the file `QUEUED` and creating a local task. It does not perform a live SFTP upload, does not download response files, does not parse raw EDI, and does not return payer or clearinghouse payloads. Tenant context comes from the bearer API key used for the public API call, not from a public request-body organization selector.\n\nDocument this module as a local validation and queueing surface around SFTP workflows. Avoid implying immediate payer delivery, SFTP receipt, claim acceptance, response polling, remittance import, or adjudication. Keep authentication wording scoped to the documented public bearer API key surface; do not generalize implementation-helper behavior into the public reference."},{"name":"Specialty Billing","description":"Specialty Billing public API.\n\nSpecialty Billing APIs expose organization-scoped aggregate visibility across anesthesia, Ambulatory Surgical Center (ASC), Durable Medical Equipment (DME), laboratory, and behavioral-health billing records, plus safe public wrappers for home-health and hospice workflow state.\n\nThe bearer API key selects the organization. Public callers should not send `organizationId`, `orgId`, or request signatures as tenant selectors in workflow request bodies; the API ignores those hints before authentication. The aggregate overview endpoint and the two local claim-status endpoints accept `specialty-billing:read` or `specialty-billing:write`. Workflow endpoints that create, update, validate, queue, acknowledge, or preview non-status records require `specialty-billing:write`.\n\nLinked patients, facilities, payer configs, patient insurance records, providers, episodes, payment periods, NOAs, referrals, authorizations, OASIS assessments, hospice elections, benefit periods, notices, census batches, claims, and denial cases must resolve inside the authenticated organization.\n\nThis public surface is intentionally conservative. It can create or update local QuickRCM records such as home-health episodes, certifications, payment periods, referrals, authorizations, hospice elections, benefit periods, notices, acknowledgements, and queue/status markers. Submission endpoints return queued/local markers and do not call clearinghouse, payer, Electronic Health Record (EHR), Centers for Medicare & Medicaid Services (CMS), or Stedi/Availity adapters inline.\n\nDraft, Additional Documentation Request (ADR), appeal, and census preview endpoints validate or preview workflow state without creating Electronic Data Interchange (EDI) payloads, cross-module ADR cases, appeal packets, payer submissions, or EHR syncs unless a future contract explicitly says otherwise.\n\nUse synthetic examples. Endpoint examples are sanitized reference samples; when a response contains a local database object or submission-attempt snapshot, examples should either include the key returned object or explicitly say they are abbreviated. Do not include real Protected Health Information (PHI), raw EDI, transcripts, S3 keys, payer portal credentials, bearer tokens, clearinghouse payloads, EHR payloads, CMS payloads, or unnecessary patient-identifying notes in examples, metadata, payload, responsePayload, rows, message, or idempotency fields."},{"name":"Support","description":"Support public API.\n\nSupport public API endpoints create and read local QuickRCM support tickets for the organization selected by the bearer API key. The current public surface has three operations: create a ticket, list tickets visible to the public API actor, and retrieve one visible ticket by `ticketId`.\n\nIn these docs, `public API actor` should be defined precisely and framed as current implementation behavior, not a permanent identifier contract. user` from an active organization member, and the Support operations verify that member and filter ticket reads by both `organizationId` and that synthetic `userId`. Current actor resolution prefers the earliest active owner member for the organization, falling back to the earliest active member when no owner exists.\n\nThe actor is not an all-organization support queue and is not a separate ticket namespace for each API key.\n\nPublic callers should not send `organizationId`, `userId`, status, resolution, assignment, comment, attachment, screenshot, or admin queue fields. The API key selects the organization and the implementation supplies the actor. Ticket `subject`, `description`, `pageUrl`, and `userAgent` are persisted and may be included in support notification email, so examples and guidance must avoid PHI, credentials, tokens, raw EDI, transcripts, S3 keys, payer portal credentials, raw EHR/FHIR responses, and vendor payloads.\n\n`pageUrl` is optional string context with a 2000-character cap and nullable storage. The contract does not validate URL syntax, so documentation should describe it as caller-supplied page context and recommend stripping patient-identifying query strings, signed URLs, access tokens, and external portal session details before submission.\n\nThese endpoints manage local SupportTicket records only. They do not expose comment threads, attachments, ticket updates, lifecycle transitions, SLA controls, admin queues, auto-ticketing from upstream modules, EHR reads/writes, payer actions, or guaranteed email delivery."}]}