Eligibility

Create eligibility check

Creates an eligibility verification workflow for the authenticated organization and returns a sanitized eligibilityCheck summary.

POSTPublic reference baselineLocal writeEligibilityoperationId: createEligibilityCheckhttps://dev-api.quickintell.com/api/v1/eligibility/checks

Public reference baselineLocal writeEligibility and discovery

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

Local write

May mutate QuickRCM records. It does not prove live payer, EHR, clearinghouse, payment, or communication execution.

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 eligibility and discovery contract generated for POST /api/v1/eligibility/checks. 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/eligibility/checks contract as a local write 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	Not indicated by OpenAPI	No generic polling contract is published from this page.
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	No file/artifact class inferred	OpenAPI text does not indicate file or artifact handling for this endpoint.
Ownership and storage keys	Not applicable unless a file field is present	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.

Related platform rules

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

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.

Eligibility public API.

Eligibility 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. Public 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. Batch 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.

What this endpoint does

Use case

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

Before calling

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

Request and response behavior

Request guidance

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.

OpenAPI marks patientFirstName, patientLastName, and patientDOB as required; the runtime Zod refinement also requires either payerId or insurance_provider.
Request serviceType is an array of up to 20 strings. Response eligibilityCheck.serviceType is a single string or null.
procedureCodes accepts up to 50 strings of up to 40 characters each.
providerId is checked against active providers in the authenticated organization before the check runs.
batchId is checked against the authenticated organization before the check is associated with a batch.

Response semantics

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

The response is a local QuickRCM summary for the authenticated organization.
payer is a nullable normalized object with payerId and payerName, not a raw payer response.
result repeats normalized status and statusCode values for integrations that consume a compact result object.
appointmentId and batchId can be null because eligibility checks may be standalone.

Errors and retries

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

400 means the body failed schema validation or the payer one-of rule.
403 indicates the authenticated API key lacks required access, scope, or organization authorization for this workflow.
429 requires rate-limit backoff rather than immediate polling.

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

This endpoint does not define path parameters.

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
patientFirstName	body	Yes	string	Patient first name for request matching. It is required in the request and omitted from the public response.	Minimum length: 1. Maximum length: 100. Potential PHI; use synthetic examples and avoid logging raw values.
patientLastName	body	Yes	string	Patient last name for prior authorization create or draft flows. Use synthetic values in public examples.	Minimum length: 1. Maximum length: 100. Potential PHI; use synthetic examples and avoid logging raw values.
patientDOB	body	Yes	string	Patient date of birth as YYYY-MM-DD or another accepted ISO-style date string. Treat as Protected Health Information (PHI).	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
memberId	body	No	string	Subscriber or member identifier from the insurance coverage context. Treat as Protected Health Information (PHI).	Minimum length: 1. Maximum length: 120. Potential PHI; use synthetic examples and avoid logging raw values.
payerId	body	No	string	Payer identifier used by QuickRCM eligibility workflows. Runtime validation requires payerId when insurance_provider is absent.	Minimum length: 1. Maximum length: 120.
insurance_provider	body	No	string	Payer display name supplied when the caller does not have payerId. Runtime validation requires insurance_provider when payerId is absent.	Minimum length: 1. Maximum length: 200.
procedureCodes	body	No	string[]	Procedure or service codes used as request context. The OpenAPI schema allows up to 50 strings.	OpenAPI does not declare additional validation metadata.
placeOfService	body	No	string	Service location code used as eligibility context, such as a Centers for Medicare & Medicaid Services (CMS) place-of-service code.	Minimum length: 1. Maximum length: 20. File, artifact, or raw-payload adjacent; keep examples metadata-only.
serviceType	body	No	string[]	Request field is an array of service type code strings; response field is a single service type string or null.	OpenAPI does not declare additional validation metadata.
providerNpi	body	No	string	National Provider Identifier (NPI) for the rendering, billing, or service provider context.	Minimum length: 1. Maximum length: 20.
providerType	body	No	string	Availity provider type code, for example AT for Professional or H for Institutional.	Minimum length: 1. Maximum length: 20.
providerId	body	No	string	QuickRCM provider identifier. The handler verifies active provider ownership in the authenticated organization.	Minimum length: 1.
appointmentDate	body	No	string	Requested eligibility date of service. Use an ISO-style date string and do not use it as a broad search field.	Minimum length: 1.
batchId	body	No	string	Optional QuickRCM bulk eligibility batch identifier. The handler verifies it belongs to the authenticated organization before associating it with the check.	Minimum length: 1.
doctor	body	No	string	Optional provider display name stored as request context, not a substitute for providerNpi or providerId.	Minimum length: 1. Maximum length: 200.
location	body	No	string	OpenAPI description is missing; publication gap.	Minimum length: 1. Maximum length: 200.
relationship	body	No	string	Subscriber-to-patient relationship value for the coverage context.	Minimum length: 1. Maximum length: 50. Potential PHI; use synthetic examples and avoid logging raw values.
subscriberFirstName	body	No	string	Subscriber first name for dependent or non-self coverage checks. Treat as Protected Health Information (PHI).	Minimum length: 1. Maximum length: 100. Potential PHI; use synthetic examples and avoid logging raw values.
subscriberLastName	body	No	string	Subscriber last name for dependent or non-self coverage checks. Treat as Protected Health Information (PHI).	Minimum length: 1. Maximum length: 100. Potential PHI; use synthetic examples and avoid logging raw values.
subscriberDOB	body	No	string	Subscriber date of birth when the subscriber differs from the patient. Treat as Protected Health Information (PHI).	Minimum length: 1. Potential PHI; use synthetic examples and avoid logging raw values.
contextData	body	No	object	Caller-supplied workflow metadata. Keep it minimal and exclude credentials, tokens, raw payer payloads, raw EDI, transcripts, and unnecessary Protected Health Information (PHI).	Sensitive credential or storage-adjacent value; use placeholders only.
forceRecheck	body	No	boolean	Boolean request flag asking for a fresh check where supported. Do not describe it as a guaranteed payer requery without stronger public evidence.	OpenAPI does not declare additional validation metadata.
checkSecondary	body	No	boolean	Boolean request flag for secondary-coverage handling. It is a request hint, not proof that a secondary payer response will be returned.	OpenAPI does not declare additional validation metadata.

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.

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

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.

201

Created eligibility check summary.

Generated from the OpenAPI response schema.

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

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.