Claims

Save claim attachment metadata

Stores claim attachment metadata tied to a claim and claim-status context, including payer, patient, subscriber, provider, encounter, and document details.

POSTPublic reference baselineFile or artifactClaimsoperationId: saveClaimAttachmenthttps://dev-api.quickintell.com/api/v1/claims/{claimId}/attachments

Public reference baselineFile or artifactClaims and remittances

Route status

Public reference baseline

Generated endpoint contract may be shown with caveats, but external publication still needs route registry and release evidence.

Publication status

Baseline reference only

Requires E6 route registry and E9 release evidence before external publication. Also requires E2 side-effect policy, E4 file and artifact governance, and E7 credential, webhook, and vendor trust policy before production recipes, SDK inclusion, or try-out access.

Authentication

Bearer API key declared

OpenAPI declares bearer API-key security for this operation.

Tenant context

API-key organization

API-key organization context is authoritative; request organizationId is not a public tenant selector.

Side-effect summary

File or artifact

Touches documents, reports, transcripts, PDFs, EDI, or generated artifacts. Metadata is safer than raw content.

Source artifact

docs/openapi/openapi.json

OpenAPI 3.1.0; API 1.0.0.

When to use this endpoint

Use this page as an internal baseline for the claims and remittances contract generated for POST /api/v1/claims/{claimId}/attachments. External use still depends on route classification, release evidence, and endpoint-specific side-effect approval.

What this does now

Documents the generated POST /api/v1/claims/{claimId}/attachments contract as a file or artifact baseline endpoint.

What this does not do

Does not prove external GA readiness, SDK readiness, live production execution, or complete module behavior. Mutating behavior still needs side-effect and retry evidence.

Not public from this page

Live external side effects, file contents, credentials, webhooks, SDK promises, and production recipes are still gated.

Headers and tenancy

Current headers and tenant authority. Target headers stay labeled as future until OpenAPI and release evidence declare them.

Header	Required	Current status	Notes
Authorization	Yes	Current	Bearer <QUICKRCM_API_KEY>. OpenAPI security: bearerAuth.
Idempotency-Key	No	Target/future	Do not claim universal header support until E3 and OpenAPI metadata exist.
X-Request-Id	No	Target/future	Use for support correlation only after approved; not declared as a standard OpenAPI header today.

Required scopes

Unclassified until E6 route metadata exists; do not infer scopes from route names.

Wrong-org behavior

Tenant-safe 404, empty list, or 403 is endpoint-specific and remains an evidence gap until E1 is closed.

Actor and audit

No public actor, audit, or correlation contract is published from OpenAPI alone.

Idempotency and retries

Retry behavior is documented conservatively because universal idempotency headers are not declared.

Topic	Status	Guidance
Current idempotency	No idempotency mechanism is declared.	Do not retry blindly. Check resource, status, batch, or job state before repeating the request.
Universal header	Not declared	Do not document universal Idempotency-Key support until OpenAPI and E3 evidence declare it.
Conflict behavior	Unresolved	Same-key changed-payload, in-flight retry, fingerprint scope, and TTL behavior remain endpoint-specific evidence gaps.

Async jobs and polling

Queued work is accepted work, not proof of completed workflow execution.

Topic	Status	Guidance
Immediate response	No 202 response declared	OpenAPI does not declare HTTP 202 for this operation.
Polling and terminal states	Endpoint-specific	Use only operation-specific status endpoints visible in OpenAPI; generic job behavior, cancellation, retries, and retention are unresolved.
Later side effects	Not proven	Do not infer background execution beyond the documented response.

Files and artifacts

File-like routes need content-class, ownership, scanning, retention, and URL policy evidence before public recipes.

Topic	Status	Guidance
Content class	Potential file or artifact	Documents, PDFs, reports, transcripts, EDI, OCR, or generated artifacts need E4 classification before public examples.
Ownership and storage keys	Evidence required	Tenant ownership must be proven before retrieval or upload docs. Never expose storage keys as public identifiers.
URLs, scanning, and retention	Unresolved unless endpoint-specific evidence exists	Short-lived URLs, MIME limits, checksums, scanner status, retention, expiration, and legal hold behavior are not implied by OpenAPI examples.

Publication warnings

Universal Idempotency-Key header support is not declared; retry only after checking endpoint-specific state.
File and artifact examples must stay metadata-only until scanning, retention, ownership, and URL policy are approved.
External or credentialed behavior needs vendor trust, credential, webhook, and callback evidence before publication.

Related platform rules

Workflow Guide Route Status Tenant Context Errors Rate Limits PHI and Security Publication Readiness Side-Effect Modes Idempotency Files and Artifacts

Evidence

Evidence	Status	Caveat
OpenAPI artifact	docs/openapi/openapi.json; OpenAPI 3.1.0; API 1.0.0.	Generated baseline contract only.
Route registry	Public reference baseline from documentation classification overlay.	E6 route registry evidence is still required before external publication.
Example validation	Generated examples are internal baseline aids.	No external publication claim; examples must pass no-PHI/no-secret/no-raw-payload/no-storage-key checks.
Last reviewed	Implementation run 20260619T-docs-impl; source boardroom packet 20260619T064820Z.	Refresh this evidence for release workspaces.
Release evidence	E9 required.	No SDK readiness, production readiness, or expanded external docs claim from this endpoint page.

Claims processing for professional, institutional, dental, attachment, claim-status, and predetermination workflows.

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

What this endpoint does

Use case

Use this before uploading or submitting a supporting document for a claim, payer request, status workflow, or additional documentation need.

Before calling

Verify the claim and claimStatusId belong to the tenant. Prepare metadata only; binary upload uses the separate attachment-file endpoint.

Request and response behavior

Request guidance

Send metadata fields needed to identify the attachment and its clinical/claim context. Do not embed raw file bytes, signed URLs, or raw EDI.

Metadata should identify the payer, patient, subscriber, provider, encounter, and document context.
Do not include binary file contents.

Response semantics

A successful response creates or updates local attachment metadata. It does not upload a file and does not submit the attachment externally.

Returns local attachment metadata.
External submission requires submitClaimAttachment after a file exists.

Errors and retries

Correct missing claimStatusId or ownership errors before retrying. File upload failures belong to uploadClaimAttachmentFile, not this metadata endpoint.

400 indicates incomplete or invalid metadata.
403 or 404 means the claim/status context is unavailable to this tenant.

Template boundary before examples

The route class, authentication state, tenancy rule, side-effect mode, idempotency status, async behavior, file policy, warnings, links, and evidence above are part of the endpoint contract. Treat generated examples below as internal baseline aids until release evidence closes.

Path parameters

Name	Location	Required	Type	Description	Validation and safety notes
claimId	path	Yes	string	QuickRCM claim identifier. The claim must belong to the organization selected by the bearer API key.	Minimum length: 1. Sensitive credential or storage-adjacent value; use placeholders only.

Query parameters

This endpoint does not define query parameters.

OpenAPI-declared header parameters

Standard platform header guidance appears in the governance panel. This table only lists operation-specific headers declared in OpenAPI.

This endpoint does not define operation-specific header parameters.

Request body

JSON fields from the generated OpenAPI schema with pilot enrichment applied where available. Nested object fields are shown with dotted paths.

Name	Location	Required	Type	Description	Validation and safety notes
claimStatusId	body	Yes	string	QuickRCM claim-status check identifier used to associate attachment metadata with a payer status or request context.	Minimum length: 1. File, artifact, or raw-payload adjacent; keep examples metadata-only.
payer	body	No	object	Payer context used by a claim, attachment, status, or AR workflow.	File, artifact, or raw-payload adjacent; keep examples metadata-only.
payer.id	body	No	string	QuickRCM payer configuration identifier returned in a nested payer summary.	Minimum length: 1.
submitter	body	No	object	Submitter entity context for claim attachment or payer transaction metadata.	File, artifact, or raw-payload adjacent; keep examples metadata-only.
submitter.id	body	No	string	Identifier from the nested payer, submitter, provider, or product object. Interpret it within that object's context, not globally.	Minimum length: 1.
submitter.state	body	No	string	US state, provider state, submitter state, or workflow state depending on context.	Minimum length: 1. Maximum length: 10.
product	body	No	object	Payer or claim product context for an attachment or claim-related workflow.	File, artifact, or raw-payload adjacent; keep examples metadata-only.
product.type	body	No	string	Type discriminator for the surrounding object, such as product type, provider type, queue type, or appeal type.	Minimum length: 1.
product.category	body	No	string	Product, correspondence, or workflow category used to route and label the record.	Minimum length: 1.
patient	body	No	object	Patient demographic context. Treat nested patient values as PHI and use synthetic examples only.	Potential PHI; use synthetic examples and avoid logging raw values.
patient.firstName	body	No	string	Person first name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
patient.lastName	body	No	string	Person last name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
patient.dateOfBirth	body	No	string	Patient or subscriber date of birth in ISO date format. This is PHI and should only use synthetic values in examples.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
patient.memberNumber	body	No	string	Payer subscriber or member identifier. Treat as PHI and avoid logging raw values.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
patient.accountNumber	body	No	string	Patient or subscriber account number from the payer, provider, or source workflow. Treat as potentially identifying financial or PHI context.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
subscriber	body	No	object	Insurance subscriber context. Treat nested subscriber values as PHI.	Potential PHI; use synthetic examples and avoid logging raw values.
subscriber.firstName	body	No	string	Person first name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
subscriber.lastName	body	No	string	Person last name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
subscriber.dateOfBirth	body	No	string	Patient or subscriber date of birth in ISO date format. This is PHI and should only use synthetic values in examples.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
subscriber.memberNumber	body	No	string	Payer subscriber or member identifier. Treat as PHI and avoid logging raw values.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
subscriber.accountNumber	body	No	string	Patient or subscriber account number from the payer, provider, or source workflow. Treat as potentially identifying financial or PHI context.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
provider	body	No	object	Rendering, billing, or service provider context. Provider identifiers can be sensitive and must be scoped to the organization.	OpenAPI does not declare additional validation metadata.
provider.lastName	body	No	string	Person last name. Treat as PHI when the person is a patient, subscriber, or contact tied to a patient account.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
provider.fullName	body	No	string	Full display name for a person or provider. Treat as PHI when linked to a patient or subscriber.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
provider.entityType	body	No	string	Provider entity classification, such as individual or organization, when the payer workflow requires it.	Minimum length: 1.
provider.npi	body	No	string	National Provider Identifier. Use a valid 10-digit provider NPI when the payer workflow requires provider identity.	Minimum length: 1.
provider.taxId	body	No	string	Provider or organization tax identifier. Treat as sensitive and use placeholders in examples.	Minimum length: 1.
provider.type	body	No	string	Type discriminator for the surrounding object, such as product type, provider type, queue type, or appeal type.	Minimum length: 1.
provider.state	body	No	string	US state, provider state, submitter state, or workflow state depending on context.	Minimum length: 1. Maximum length: 10.
provider.zip	body	No	string	Postal code for patient, subscriber, or provider address context. Treat as PHI when tied to a person.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
provider.address	body	No	string	Street address for the patient, subscriber, provider, or recipient context. Treat address values as PHI when tied to a person.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
provider.city	body	No	string	City portion of a patient, subscriber, provider, or recipient address. Treat as PHI when linked to a person.	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
encounter	body	No	object	Encounter-level service context that ties claim attachment metadata to service dates, request numbers, or visit details.	File, artifact, or raw-payload adjacent; keep examples metadata-only.
encounter.serviceFrom	body	No	string	Start date for the healthcare service period. Use an ISO date string.	Minimum length: 1.
encounter.serviceTo	body	No	string	End date for the healthcare service period. Use an ISO date string and keep it on or after serviceFrom.	Minimum length: 1.
encounter.requestNumber	body	No	string	Payer or internal request number associated with an encounter, authorization, claim status, or attachment workflow.	Minimum length: 1. File, artifact, or raw-payload adjacent; keep examples metadata-only.
claimNumber	body	No	string	Human-facing or payer-facing claim number used for reconciliation. It is not always the same as QuickRCM claimId.	Minimum length: 1.
controlNumber	body	No	string	Clearinghouse or transaction control number used to correlate claim, attachment, or status workflow records.	Minimum length: 1. File, artifact, or raw-payload adjacent; keep examples metadata-only.
status	body	No	string	Workflow status filter or target status. Valid values depend on the endpoint schema and module state machine.	Minimum length: 1.

Generated request example

Generated examples are baseline contract aids only. They are not external publication evidence and must not include real PHI, credentials, raw vendor payloads, raw EDI, transcripts, storage keys, or signed URLs.

{
  "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"
}

Successful responses

Generated response examples show the baseline OpenAPI contract. Tenant identifier echo, PHI redaction, pagination, money, date/time, and enum semantics remain endpoint-specific publication checks.

200

Saved attachment metadata.

Generated from the OpenAPI response schema.

{
  "success": true,
  "data": {
    "claimId": "00000000-0000-4000-8000-000000000001",
    "claimStatusId": "00000000-0000-4000-8000-000000000001",
    "status": "SAVED"
  },
  "meta": {
    "organizationId": "00000000-0000-4000-8000-000000000001"
  }
}

Error responses

Errors must remain sanitized. Do not include raw payer, EHR, SFTP, SMTP, Stripe, LLM/OCR, browser automation, file, transcript, EDI, worker, or vendor payloads.

400

Invalid request.